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INTRODUCTION TO OS-9 
-05-9 Level One is a versatile multiprogramming / multitesking 
«operating system for computers utilizing tne Motorola 6849 
microprocessor. It is well-suited for a wide | range of 
applications on 68@9 computers of almost any size or complexity. 
Its main features are: - E Wi E | 


* Comprehensive management of all system resources: memory, - 
input/output and CPU time. SR l 


* A powerful user interface that is easy to learn and use. 
N rue multiprogramring operation. | 

* Efficient operation in typical microcomputer gongiguretions. 
* Expandatle, device-independent urified 1/0 system. 

x» Full support for modular BOMed software. : 
^* Upward and downward compatability. 


This manual is intended to provide the information necessary 
| te install, maintain, expand, or write assembly-language software 


^» for OS-9 systems. It assumes that the reader is familiar with the 


= 6889 architecture, instruction set, and assembly language. 


- HISTORY AND DESIGN PHILOSOPEY | : 
| 0S-9 is one of the results of the BASICOS Advanced 6809 


^^ Programming Language development effort undertaken by Microware 


and Motorola from 1978 to 1980. During the course of the project 
| it became evident that a fairly sophisticated operating system 
would be required to support BASIC29 and similar high-performance 
6899 software. ` ; AE 


| O0S-9's design was loosely modeled after Bell Telephone 
Laboratories” “UNIX” operating system, which is becoming widely 
recognized as a standard for mini and micro multiprogramming ~ 
operating systems because of its versatility and relatively 
simple, yet elegant structure. Even though a "clone of UNIX for 


the 6829 is relatively easy to implement, there are a number of ` 


problems with this approach. UNIX was designed for fairly large- 
scale minicomputers (such as large PDP-11s) that have high CPU 
throughput, large fast disk storage devices and a static 1/0 
environment. Alsc, UNIX is nct particulary time cr disk-storage 
efficient, especislly when used with low-cost disk drives. 
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For these reasons, 0S-9 Was designed to retain the overall 
concept and user interface of UNIX, but its implementation is 
conSiderably different. OS-3°s design is tailcred tc typical 
microcomputer rerformance ranzes and operational environments. As 
. an example, OS-9, unlike UNIX, does not dynamically swap running 

programs on and off disk . This is tecause floppy disks and many 
lower-cost Winchester-type hard disks are simply too slow to do 
this efficiently. Instead, 05-9 always keeps running programs in 
memory and emphasizes more efficient use of available ROM or RAM. 


OS-9 also introduces some important new features that are 
intended to make the most of the capabilities of third-generation 
microprocessors, such as Support of reentrant, position- 
independant. software that can be shared by several users 
Simultaneously to reduce overall memory requirements. : a 


Perhaps the most innovative part of 0S-S is its memory 
module" management system, which provides extensive support for 
modular software, particularly ROMed software. This will play an 
increasingly important role in the future as a method of reducing 
software costs. The “memory module and LINK capabilities of 
0S-9 permit modules to be automatically identified, linked 
together, shared, updated or repaired.. Individual modules in ROM 
which are defective may te repaired (without reprogramming the | 
ROM) by placing a “fixed” module with the same name, but a higher 
revision number into memory. Memory modules. have many other 


. advantages, for example, O0S-9 -can allow several programming 


languages to share a common math subroutine module (such as 
Motorcla/s new MC6839 floating voint subroutine ROM). This same 
module could automatically be replaced with a module containing 
‘drivers for a hardware arithmetic processcr witncut any Change to 
the programs which call the module. | | 


Users experienced with UNIX should have little difficulty 
adapting to OS-9. Here are some of the main differences between ` 
the two systems: | | > 


1. OS-9 is written in 6809 assembly language, not C. This 
| improves rrogram size and speed characteristics. | 


2. O0S-9 was designed for a mixed RAM/ROM microcomputer memory 
environment and more effectively Supports reentrant, 
position-inderendent code. AME: js | 


3. OS-S introduces the “memory module concept for organizing 
object code with built-in dynamic inter-module linkage. j 


4. O0S-9 supports multiple file managers: moduies 
that interface a class of devices to the file system. 


5. “Fork” and "Execute" calls are faster and more memory 
| efficient than the UNIX equivalents. NM can 
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SYSTEM BARIWARE REQUIREMENTS ` 


The OS-S operating system is/ made up of "building blocks" called 


modules which are autoratically located aná linked together when 
the system starts up. This makes it extremely easy to- 


reconfigure the system. For example, reconfiguring the system tc 
handle additional devices is simply a matter of placing the 


correspording modules into memory. Because 05-9 is so flexible, 


the "minimum hardware requirements are difficult to define. A 


bare-tones LEVEL I system requires 4K of ROM and 2K of RAM, which 
may be expanded to 56K RAM. A large LEVEL II system might have. 


several hard disks, multiple terminals, and a megabyte of RAM 
using memory management hardware. ; | SET 


Below are the requirements for “typical” OS-9 computer systems. 
Actual hardware requirements may vary depending upon the 
particular application. 


* 6809 MPU 


o 4E Bytes RAM Memory for Single Board Computer Systems 
DAK Bytes RAM Memory for Assembly Language Software 


APE Bytes RAM Memory for High Level Languages such as BASICÓS 


(RAM Must Be Contigucus From Zero Up) 


e AK Bytes of ROM: 2K must be addressed at $F800 - $FFFF, the 
other 2K is position-independant and self-loceting. 


Some disk systems may require three 2K ROMs. 


Single board computers and other ROM based systems may require 
an aéditional 6X of ROM for modules which are normally loaded 


from the bootstrap file (6K includes SEELL and DEBUG modules). — 


* Disk or cassette tape I/O device. 


Vë Console terminal and interface using serial, parallel, or 
memory mapped videc. se Ee 


* Optional printer using serial or parallel interface. 


* Optional real-time clock hardware. 


1/0 device controller addresses can te located anywhere in the 
memory space, however it iS good practice to place them as high 


as possible to maximize RAM expansion capability. Standard 
Microware-supplied 05-9 packages for computers made by popular 


manufacturers usually conform to the system's customary memory 
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TEX KERNEL AND ITS BASIC FUNCTIONS 


The heart of OS-9 is called the “kernel” which serves as the 
system's administrator, supervisor, and resource manager. It is 
about ZK bytes long and normally resides in ROM with 2K at the 
highest memory addresses ($FB00 - $FFFF). ItS main fuctions are: 


1. System initialization after restart. 
2. Service request processing. E 

3. Memory management. 

4. MPU management (multiprogramming) . 


5. Interrupt processing. 


Notice that input/output functions were not included in the. 
list above; this is because the kernel does not directly process 
them. Instead, there is a separate I/O system constructed from a 

number of standard (or user-supplied) program modules selected to 
match. the computer’s specific hardware configuration. This is 
why OS-S can be easily tailored to almost any 6629 comruter’s 
hardware configuration. Tne kernel passes 1/9 service requests 
directly to anotner subsystem called the Input/Output Manager , 
or “IOMAN”. Its function is to decode the I/O service request to 
select a specific “file manager and a specific I/O driver , 
which do the actual processing. The. file managers and I/O 
drivers are also modules selected for the specific system 
configuration. : 


After a hardware reset, the kernel will initialize the system 
which | involves such things as locating ROMs in memory, 
datermining the amount of RAM “available, lcading any required 
modules not already in ROM from the bootstrap device, and other 
related tasks. roe 


Service requests (system calls) are used to communicate tetween 
OS-9 and assembly-language-level programs for such things as 
allocating memory, creating new processes, eic. In addition to 
these callatle functions, there are other real-time functions - 
such as time-slicine, timekeeping, ard interrupt service, which 
are automatic and occur routinely during normal system operation. 
"E | 
Memory management is a very important cperating system 
responsibility. One way in which 05-9 is ifferent than other 
operating systems is that it manages both the physicai assignment  . 
AND the logical contents of memory, by using entities called 
gemory modules .| All programs are. loaded in memory module 
format, allowing 0S-9 tc maintain a director, which contains tne : 
name, address, and other related informetion about each module in. 
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memory. "These structures are the foundation of 0S-Ss moduler 


| software environment. Some of its advantages are: eutomatic run- 
time linking of programs to libraries cf utility modules; 


ev 


automatic "sharing of reentrant proarams; replacement cf small 
sections of large programs for update or correction (even when in 
RCM); etc. |. AO E d 


0S-9 is a multiprogramming operating system, which means that 
several independent programs called processes can te executed 
Simultaneously. Each process can have access tt any System 
resource by issuing appropriate service requests to 0S-S. 


Multiprogramming uses a hardware real-time clock that generates 
interrupts at a regular rate of about 10 times per second. ..MPU.. 
time is . therefore divided into periods typically 180 - 


milliseconds in duration. This basic time unit is called a 
tick’. Processes that are "active" (meaning not waiting for 

some event) are run for a specific system-assigned period called 

a time slice’. The duration of the time slice depends on a 


-process's priority value relative to the priority of all other 


active processes. Many 0S-S service requests are available to 
create, terminate, and control processes. 


Interrupt processing is another important function of the 


kernel. All hardware interrupts are vectored to. specific 
processing routines. IRQ interrupts ere handled by a prioritized 


polling system which automatically identifies the scurce of the 
interrupt and dispatches to the associated user cr system defined 
service routine. The real-time clock will generate IRỌ 
interrupts. = SWI, SVIZ, and SWIG interrupts are vectored to user- 


. definable addresses which are "local" to each procedure, except 


that SWI2 is normally used for 05-9 service requests calls. The 


NMI and FIRO interrupts are not normally used and are vectored 


through a RAM address to an RTI instruction. 


At any given moment, OS-9 is in one of two states: "user 
state when a user process is in execution, and system state 


during execution of 0S-S routines which occurs after any system 
service request cr a hardware interrupt. | 
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MULTIPROGRAMMING 


This section of the manual deals with the following aspects E. 
multiprogramming under the OS-9 operating system: rrocess 


creation, process states, execution scheduling, and signals as a 


.means of inter-process communication. 


PROCESS CREATION 


S New processes are created when an existing process executes a 
"fork" service request. Its main argument is the name of the 
program module (called the primary module ) that the new process 
is to initially execute. OS-9 first attempts to find the mocule 
in. the “module directory , which includes the names of all 
program modules already present in memory. If the module cannot 
be found there, 0S-9 usually attempts to load into memory a mass- 
^storage file using the requested module name as e file name. 


. Once the module, has been located, a data structure callec a 

process descriptor is assigned to the new precess. The 
process descriptor is a 64-byte package that contains information 
about the process, its state, memory allocations, priority, queue 
pointers, etc. The process descriptor is automatically 
‘initialized and maintained by 0S-9. Tne process. itself hes ro 
need, and is not permitted to access the descriptor. 


The next step in the creation of a new process LS allocation 
of data storage (RAM) memory for the process. The primary 
 module's header contains a storage size value that is used unless 


LA 


the "fork system call requested an cptionally larger size.  C5-9. 


then attempts to allocate a CONTIGUOUS memory area of this size 
from the free memory space. | | mE "s 


If any of the previous steps cennot be performed, creation of 


the new process is abcrted, and the process that originated the 
fork is informed of the error. Otherwise, the new process is 
added to the active procass queue for execution Scheduling. 


The new process is also assigned a unicue number called a 


e A 
process IL which is used as its identifier. Other precesses 


can cormunciate with it by referrirg to its ID in various „syster 


galls. The process also has associated with it à user ID which 
is used to identify all processes and files telcnging to a 
particular user. The user ID is inherited from the parent 
process. 


Processes terminate when they execute an “EXIT” system service 
request, or when they receive fatal Signals. The process: 
termination closes any open patas, deallocates its memory, and 


unlinks its primary module. 
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PROCESS STATES 

o Each process can pe in one of three states: i 
ACTIVE: — The process is active and ready for executions 
WAITING S The EE is suspended until some event occurs. 


SLEEPING - The EH is suspended for a Spec ific id of 
time. 7 


There is a queue for each process state. The queue is a 
linked list of the "process descriptors of processes in the 
corresponding state. State changes are performed by moving a 
process descriptor to another queue. | g 


The Active State: 


This state includes all “runnable” processes, which are given 

- time. slices for execution according to their relative priority 

with respect to all other active processes. The scheduler uses à 

"pseudo-rovnd-robin schere that gives all active processes some 
CPU time, even 1f they nave a very low relative priority. 


~The Wait State: 


This state. is entered when a process executes a WAIT system 
| service request. The process remains suspended until tne death ` 
of any of its descendent EEN or, until it receives e. 
signal. | 5 | 


The Sleeping State 


This state is entereë when a process executes a SLE EP service 
request, which specifies a time interval for which the process is 
to remain suspended. The process remains asleep. until the 
specified time has elapsed, or until a signal is received. 
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EXECUTION SCHEIULING 


The kernel contains a scheduler that is responsible for 
allocation of CPU tire to active processes. OS- uses a 
scheduling algorithm that ensures all processes get some 
execution time. | & | 


All active processes are members of the "active process 


queue , which is kept sorted by process age . Aze is. a count of 
how many process switches have occurred since the process” last 


time slice. When a process is moved to the active process queue 
from another queue, its age is initialized by setting it to the 
process”. assigned pricrity, i.e., processes having relativel; 
higher priority are placed in the queue with an artificiali; 
higher age. Also, whenever 4 new process is activated, toe ages 
of all other processes are incremented. | 


Upon conclusion of the currently executing process” time | 


slice, the scheduler selects the process having the. highest age 


to be executed next. Because the queue is kept scrted by age, ` 
this process will be at the head of the queue. At this time the 
ages of all other active processes are incremented (ages are 


never incremented beyond 255). nee M. 


An exception is newly-ective processes that were previously 


deactivated while they were in the system state. These processes 


are noted and given higher priority than others because trey are 


usually executing critical routines that affect Shared. system 
resources and therefore could te blocking cther unrelated 
processes. N | | TE LM 


When there are no active processes, the kernel will set itself 


up to handle the next interrupt and then execute a Ba ER 


instruction, which decreases interrupt latency time. 
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SIGNALS 


"Signals" are an asynchronous control mechanism used for 


inter-process communication and control. A signal tenaves like e 
software interrupt in that it can cause a process to suspend a 
program, execute a specific routine, and afterward return to the 
interrupted program. Signals can be sent from one process to 
another process (by mears of the SEND service recuest), or they 
can be sent from OS-9 system routines to a process. 


Status information can be conveyed. by the signal in the form 
of a one-byte numeric value. Some of the signal codes (values) 
have predefined meanings, but all the rest are user-defined. The 
defined signal codes are: me 


KILL (non-intercertable process abort) 
WAXEUP — wake up sleeping process 
KEYBOARD ABORT — Ele 

- KEYBOARD INTERRUPT | 

- 255 USER DEFINED 


PANE © 
inn now 


When a signal is sent to a process, the signal is noted and 


saved in the process descriptor. If the process is in the 
sleeping or waiting state, it is changed to tne active state. It 


then becomes eligible for execution according to the usual MPU 
scheduler criteria. When it gets its next time slice, the signel 


is processed. 


What happens next defends on whether or not “the process had 
previously set up a signal trap (signal service routine) by 
executing an INTERCEPT service request. If it had not, the 
process is immediately aborted. It is also eborted if the signal 
code is zero. The abort will be deferred if the process is .in 
system mode: the process dies upon its return to user state. 


If a signal intercept trap has been set ur, the process 
resumes execution at the address given in the INTERCEPT service 
request. The Signal code is passed to tnis routine, which should 


terminate with an RTI instruction to resume normal execution of | 


the process. 


NOTE: "Wakeup signals activate a sleeping process: they DO NOT 


. Vector through the intercept routine. | | 


If a process has a signal pending (usually because it has not 
been assigned a time slice since the signel was received), and 
some other process attempts to send it another signal, the new 
Signal is aborted and the send service request will return an 


error status. The sender Should then execute a “sleep service 


request for a few ticks before attempting to resend the signal, 
so the destination process has an opportunity to process the 
previously pending signal. | | 
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MEMORY MANAGEMENT 


MEMORY ALLOCATION 


All usable RAM memory must be contiguous from address £ 
upward. During the 05-9 start-up sequence the upper bound cf RAM. 
is detemined by an automatic search, or from tae configuration 
module. Some RAM is reserved by 05-9 for its own data structures. 
at the top and bottom cf memory. The exact amcunt depends on the 
sizes of system tables that are specified in the configuration . 
module. | | 


All other RAM memory is pooled into a "free memory space. 
Memory Space is dynamically taken from and returned to this pool 

^J as it is allocated or éeallocatei for various purposes. Tie. 
|. basic unit of memory allocation is the <56-byte page + Memory 
is always allocated in whole numbers of pages. Se 


The data structure used to keep track of memory allocation is 

a S2-byte bit-map located at addresses 50100 — $G11F. Each bit 
^N in this table is associated with a specific page of memory. sits 
"are cleared to indicate that the page is free and available for 
assignment, or set to indicate that tne page is in use cr that no 
RAM memory is presert at that address. Be 


| | 
Automatic memory allocation occurs when: 
| | 


1. Program modules are loaded into RAM. 
2. Processes are created. ` | | 
3. Processes request additional RAM. 
4. OS-9 needs I/O buffers, larger tables, etc. 


All of the above usually have inverse functions that cause 


previously allocated memory to be deallocated and returned to the 


free memory pool. 


In general, memory is allocated for program modules and. 
buffers from high addresses downward, and for process data areas 
from lower addresses upward. | ~ 3 

| | l i 
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TYPICAL MEMORY MAP 
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The map above is for a “typical” system. Actual memory sizes and 
addresses may vary depending on the exact system configuration. 
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MEMORY MODULES 


All programs used on 0S-9 systems must use the memory module 
format and | conventions. Many of 0S-3^'s extraordirary ` 


capabilities would not be possible without them. 


The memory module concept allows OS-9 tO manage the logical. 
contents as well as the physical. contents of ER The basic 
idea is that all programs are. discrete, named units. The - 
operating system keeps track of modules which are in memory at. 


all times by use of a “module directory”. It contains the 
addresses and a count of how many processes are using each 


J module. When modules are loaded into memory, they are added to 


the directory. When they are no longer needed, their memory is 
deallocated and their name removed from the directory (except 
ROMS, which are discussed later). In many respects, modules 
and memory in general, are managed dust. like a disk. In fact, tne 


disk and memory management sections of 035-9 Share many . 


^*$ubroutines. 


Each module has three parts; a module neader, module body and 


a cyclic-redundancy-check (CRC) value. . The header contains: 
information | that describes the module and its use.. "his 
information includes: the modules size, its type (machine 


language, BASIC@9 compiled code, etc); attributes (executatle, 
—reentrant, etc), data storage memcry requirements, execution 
starting address, etc. Tre CRC value is used to verify the 
integrity of a module. |. > | . TN S 


There are several different kinds of modules, each type having 


a different usage and function. Modules do not have to be 


complete programs, ,, or even 6889 machine language. They may 


contain  BASICOS 'I-code", constants, single subroutines, 

subroutine packages, etc. The main requirements are that modules 

do not modify themselves and that they be position-incependent so 

05-9 can load or relocate then wherever memory Space is 

available. In this respect, the module format is tae 05-9 

equivalent of load records used in older-style operating 
systems. | V 
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MEMORY MODULE STRUCTURE 


At the beginning Dee E of the module is the | module 


header, which can have several forms depending on the modules ` 


usage. The header is described more thoroughly later in this 
section. Following the header is the program/constant section 


‘which is usually pure code. Tne module name string is inciuded 
somewhere in this area. The last three bytes of the module are a 


three-byte Cyclic Redundancy Check (eee) value used to verify the 
Ve of the module. 


MODULE FORMAT 


MODULE HEADER 


1 1 
1 i 
j Des 
$ { 
d i 
] A 
n ME 
i PROGRAM d 
1 OR CONSTANTS y 
i CRC 4 
i + 


The 24-tit CRC is 3éfforned over the entire module from the 


first byte of the module header to the byte just before the CRC 


itself. The CRC polynomial used is $89£FES. 


Because most 0S-9 family software (such as the ee 
automatically generate the module header and CRC values, the 
programmer usually does not nave to be concerned with writing 
routines to generate them. | 
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MANUAL 


MODULE HEADER DEFINITICNS 


rmat of module headers may seem complicated at first, 


but in practice they are simple to create and use because  OS-9 
family software such as BASIC29, the assembler, and many utility 


programs a 
idea to 

how they w 
identical: 


. MODULE 
OFFSET 


40,51 


$2.99 


$6 
$7 
$8 


Module Size. 


utomatically generate modules and headers. It is a good 
have a general understanding of what they look like and 
ork. The first nine bytes of all module headers are 


DESCRIPTION 


Sync Bytes ($87,5CD). These two constart 


bytes are used to locate modules. 


The overall size of the module 
in bytes (includes CRC). 


Offset to Module Name. The address of the 

module name string relative to the start. 

(first syne byte) of the module. The name 

string can be located anywhere in the module 

and consists of a string of ASCII characters 

having the sign bit set on the last character. 
: | 


Module Type/Langauge Type. See text. 
Attributes/Revision Level. See text. 


Header Check. The one’s compliment of the vertical 
parity (exclusive OR) of the previous eight bytes. 


Type/Language Byte 


The mod 
of byte 
convention 
type codes 


NOTE: O is 


ule type is coded inte the four most significant tits 
6 of the module header. Eight types are pre-defined by 
, Some of which are for 0S-9°s internal use only. The 
are: | qoM 


Program module 

Subrcutine module 
 Multi-module 

Data module ` 

User-definatle 

OS-S System module 

0S-9 File Manager module 

OS-9 Device Driver module | 

OS-G Device Descriptor module 


not a legal type. 
| | 


1981 Microware Systems Corporation 
- PAGE 14 — | ET. 


(C) 1982, 


05-9 LEVEL ONE SYSTEM PROGRAMMER’S MANUAL — ` 
Memory EE Ze, 


The four least significant bits of tyte 6 describe the language 
type as listed below: S 


DATA 

6869 object coce 
BASIC£9 I-code 

PASCAL P-code 

-COBOL I-code 

5-15 Reserved for future use 


ib NA @ 


The purpose of. the language type is So high-level language 
run-time Systems can verify that a module is of the correct type 
before execution is attempted.  BASICES, for example may run 
either I-code or 68£9 machine language procedures EE ty 
checking the language type code. | | 


Attribute/Revision Byte 


The upper four bits of this byte are reserved for module 
attributes. Currently, only tit 7 is defined, and when set 
indicates the module is reentrant and therefore. ‘sharable. x 


The lower four bits ere a revision level from zero (lowest) to 
fifteen. If more than one module hes the same name, type, 
language, etcs, OS-9 only keeps in the module directory the . 
module having the highest revision level. This is how ROMed 
modules car be replaced or patched: you load ea new, equivalent 
module having a higher revision level. Because “all “modules 
locate each other by using the LINK system cail which searches 
the module directory by name, it always returns tne EES 
revision of the module, wherever it may be. EN 


NOTE: A previously linked module can not te replaced until adu 
processes which linked to it nave unlinked it: (after its lint 
count goes to zero). | | 
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‘TYPED MODULE HEADERS 


As mentioned es the first nine bytes of the. module ore 
are defined identically for all module types. There is usually 


more header information immediately following, the layout and | 


Meaning varies derending on the specific module type. Module 
types $C - $F are used exclusively by 0S-9. Their format is given 
elsewhere in this manual. | i'n | 


The module type liiusicsted "below is the general-purpose 
user format that -is commonly used for OS-S programs that are 
called using. the FORK or CHAIN system cells. These modules are 
the “user-defined types having type codes cf @ through 9. They 
have six more Ed in their headers defined as follows: SÉ 


we 


MODULE DESCRIPTION 
OFFSET 


-$9,$4 = Execution Offset. The program or subroutine's 

ke . Starting address, relative to the first byte of 
the sync code. Modules having multiple entry 
points (cold start, warm start, etc.) n aave 
a branch table starting at this address 


EXT 


Permanent Storage Requirement. This is the | 
minimum number of bytes of data storage ur 
required to run. This is the number used by 
FORK and CHAIN to allocate a process” data 
area. Së 


If the module will not be directly executed by a 

— CHAIN or FORK service request (for instance a. 
subroutine package), this entry is not used by 05-9. 
It is commonly used to specify the maximum stack size 
required by reentrant subroutine modules ine 
calling program can check this value to determine 

if the subroutine has enough stack space. 
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— MODULE = EXECUTABLE MEMORY MODULE FORMAT 


| OFFSET 
: EE. Ee nim mm O i aan OD cane mae ae: —— mn e mem ne Se mmm een em MÀ anis 
$900 ! | b le ! 
+=- Syne Bytes ($87CD)  --+ Es i 
$61 p MES f ! 
em um art unes ces mn enm, ano nee ame ar ame que aum em ne ee am m m etre amm ure tio uu mio vm ao c s ed te ! 
$82 ! ! E x ! 
| += Module Size (bytes)  --+ EJ ! 
$23 k | p 1. A 
$04 I ee ! Los l 
p- Module Name Offset -—* header ! 
$05 — I! | E ! parity ! 
| A e me ELE ED ! | i 
$26 ! Type oo! Language — |! Ser ] 
———————— Qd AR GE ! 
$07 . ! Attributes ! Revision ! pocte dl 
Á R—————— MÀ e —— e — —— e e + -——-—--—- ) module 
-$98 ! | Header Parity Check LS Lui CRC 
dom are ee À ae € — ee — À a te ane ss ym e e ~E Ss 
$29 ! we { 
CSC Execution Offset ed 
| SOA SE N ! 
wh E dem m ae ee com ome !— e —— À — —— ce er  — € À en oe a 
ml $052 ! | A. 
| | te Permanent Storage Size --+ 
Sec — ! | ! 
y o — M MÀ MÀ in me em — M e e + 
$ 9D (Add “1 ea header 


extensions loceted here) 


Module Body : 
object code, constants, etc. 


L 8 ! 


em gung goë geg OE geg fon geg el ll ER aam OE gn ee gea rä sn SH E 


o | | — 
f CRC Check Value ae ! 
— —e 
i DES 
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ROMED MEMORY MODULES. 


When OS —9 starts after a system reset, it searches the entire 
memory space for ROMed modules. It detects them by locking for. 


the module header syrc code ($87,$CD) which are unused 6809 
opcodes. When this byte pattern is detected, the header check is 
performed to verify a correct header. If this test succeeds, the ` 
module size is obtained from the header and a 24-bit “GRO is 


performed over the entire module. If the CHC matches correctly, 
the module is considered valid and it is entered into the module 
directory. The chances of detecting a faise module . are 
virtually nil. | 


In this manner all ROMed modules present in the system at 


startup are automatically included in the system module 1 


directory. Some of the modules found initially are various parts 
of 08-9: file managers, device driver, tne configuration module, 


etc. E 


After the module search oOS-9 links to xnicnever of its 


component modules that it found. This is the secret of OS-S"s 
extraordinary adaptablity to almost any 6809 computer; it 


automatically locates its required and optionai component 


«modules, wherever they are, and rebuilds the system each time 


that it is started. 


ROMS containing non-system.moáules are also searched so. any 


—user=supplied software is located during the start-up process and x 


entered into the module directory. | 
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op SYSTEM COMPONENTS: TEE MAJOR MODULES 


|  0$-9 is composed of a number of modules. Some of ‘the 
component modules are required. Others are optional and included 


in a particular computer to meet a desired performance level or 


to support specific hardware or 1/0 devices. Below is a list of 
the required and optionel modules: | GE 


REQUIRED: Kernel (2K must reside at $F8a0-$FFIF) 
oe Configuration Moaule if 


OPTIONAL: System Bootstrap Module 

d Input Output Manager (IOMAN) | 
File Manager (SCFMAN or REFMAN) 
Device Drivers ` T3 | 
Device Descriptors H^ Ze e - o Det 
System Initialization Module (STSGO) 


TEE KERNEL ` 
The kernel is the heart of 0S-9. Its purpose is to: 


1. Initialize the system after reset ` 
2. Process system calls. : 
3. Manage RAM memory. 


4. Manage the module directory. 
5. Service interrupts. 


^ The kernel’s total size is approximately 3k bytes, which is 


partitioned into two sections. The first section called "0S9" 
contains the interrupt vector tables which must be located at 


$FFEG through $FFFF. | The second section called "OSOP2'" can be. 


located anywhere in memory. Both sections must te in ROM! If 
the target system bootstraps other 05-9 component modules into 
RAM from disk or tape (standard Microware supplied versions do 
so), OS-O fits into a 4X ROM or a pair of 2E ROMS, leaving an 
extra. 1K for a bootstrap device driver module. Some lengthy disk . 
driver modules that are larger than 1K require an additional ROM.. 
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THE CONFIGURATION MODULE 


This module defines system Startup parameters ard must also be. 
in ROM (it fits in the same ROM as the kernel). It „is a non- — 
executable module named INIT and nas type system” (code $C). 
It is scanned once during the system startup. It begins with the 
standard header followed by: ) 


MODULE OFFSET x | | | E. | 
| $9,5$A,$B This location contains the forced limit of free 
| | RAM memory. It may be used to cverride 005-9's 
automatic top-of-RAM search SO that memory may be 

reserved for speciai purposes. ` | V d pe : 


E Number of entries to create in > the IRQ polling 
tatle. One entry is required for each interrupt 
generating device control register. | od 


$D ` Number of entries to create in the system device 
tatle. One entry is required for each device in 
the system. SE ) 


O$EQSE. Offset to the intitial startup module name 


string. This is the name of the first moduie tpud 
te executed after Startup, usually |. SYSGO + 


There must always be a startup module. 


$19,511 Offset to the initial standard path string 

| (typically /TERM). This path is opened as the 
standard paths for the initial startup module. 
This location should contain zero if there is 
none. | 


$12,$13 Offset to the default directory name string 
(normally /D0). This device 15 assumed when . 
device names are ommited from patnlists. If the 
system will not initialy use a mess storage 
device (such as in ROM based systems) this. 
location should contain a zero. ` 


$14,$15 Offset to bootstrap module name string. If 03-39 
cannot locate any of its other required modules 
in ROM, it will call the tcotstrar. module which 
attempts to load tnem from a mass-storage device. 


$16 to N All name Strings go here, followed ty three CRC 
bytes. Name strings must nave the sign vit. 
(bit 7) of the last character set. | | 


(also see the memory rodule format diagrams in Appendix be 
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The “default” configuration: ET EE in the OS<S kernel 
ROM can be replaced by e user-sup plied: module. Just make your Own 
module .accerding to the specification S above, giving it a 
revision level (byte 7 of .the Ke of one or higher. This 
module must be in ROM. 


THE SYSTEM BOOTSTRAP MODULE 


This module loads several of 05-9s required and optional 
modules from the bootstrap file cn a mass-storage device. Luring 


the kernel’s startup sequence, it tries to link to other modules .. 


such as IOMAN. If they are not in memory, the kernel will call 
the. beotstrap module to load them from mass-storage. Some CS-9 
systems will. have all required modules in ROM so the. bootstrap. 
module is not needed. Also see ane OS —y GE a ROM Based 
System . 


In many systems, it is not cost efffective or otherwise practical 
to place all of 05-9 into ROM. In these systems, only the 
kernel, configuration, end bootstrap. modules are ROMed. When the 
system is reset, the kernel will cali the bootstrep module which 
attempts to load the boostrap file into memory from a mass- 
storage device such as disk or tape. The bootstrap file contains 
all modules required by 05-9 that are not already in ROM, and 

other optional modules which should. be loaded into memory at 
startup time. Below is a list of the modules which are typically 
loaded from the bootstrap file (tne actual contents may vary - for 

a particuler system or hardware. EEN 


MODULE NAME 


IOMAN . Input Output Manager 


REF & Random Block File Manager 

scr | - Seguential Character File Manager 

DSK Disk Driver (name varies with controller) 
ACIA ACIA Driver 

PIA. -. PIA Driver 

Clock Real-time-clock interface module 

De Drive zero device descriptor (DISK) 

Di Drive one device descriptor (DISK) 

TERM : Console terminal device descriptor (ACIA? 

T1 | Secondary terminal device descriptor (ACIA) 
P ij Printer device descriptor (PIA) | 
KA | Secondary printer device descriptor (acta) 
SYSGO System startup module 


SHELL | System command interpreter 
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OTHER IMPORTANT MODULES ` 


It is possible for very simple computers that don't have 
standard I/O devices to get by with just the kernel. But most 
practical systems will be interfaced to a terminai and some kind 
of mass storage or communications device. . Additional 0S-9. 
modules interface the kernel to the I/O system. These ere the 
1/0 Manager ( IOMAN ), one or more File Manager modules, one or 
more Device Driver modules, and one or more Device descriptors. 


RUNNING OS-9 AS A ROM BASED SYSTEM 


For many aplications using OS-9, a mass storage device such as & 
disk is either too costly or otherwise inappropriate. Certain 
applications require that the operating system be functional 
before a mass-storage device 1s used; for instance, it may be 
necessary to be able to run a system diagnostic program'such as - 
the interactive DEBUG module before the uSing the disk drives. 
0S-9 can eaisly be tailored to meet these needs. To run QS-9 as 
| a ROM based system, all that is required is to adjust two 
parameters in the system configuration medule (INIT) and put a 
few modules into ROM. Below is a description of how the INIT 
module must be adjusted: | ; | 


A. If the system will not use a mass storage device, set the 
offset to the default mass-storage device name string to 
zero in the INIT module. 


B. If it is not necessary to bootstrr from a mass-storage 
device, set the offset to ihe BOOT module name string to 
zero in the INIT module. ` | tet | 


Below is a list of the name and approximete size of the mcdules 
which are required for 05-9 to start up and te fully functional 
(complete with the SHELI command interpreter): m id 


MODULE SIZE 

Oss. | ded 0S-9 Part One. 

OS9P2 4CB OS-S Part Two 

IOMAN SE 1/0 Manager SE ) | 

SCE EDO ^ Sequential Character File Manager 
ACIA ` -~ $183 ACIA device driver ` ES 

TERM | $38 Console terminal device descriptor 
SYSGO | $66 |. System initialization module 

INIT | $24 System configuration module ` 
SHELL | $403 Shell command line interpreter 


a AM ome en wor 


$1CAL = 7329 System ROM requirements 
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This set. of modules is EE sofor o a ^ single. board 


microcomputer, the actual System. requirements will very (see. the 
section of this manual on “SYSTEM HARDWARE REQUIREMENTS"). In 


some applications it may be desireble to include a real-time- 
clock driver module, bootstrap module (so that a mass-storage 
device may be used after startup), cr the interactive DEBUG 
module for system diagnostics purposes. Che. name and size of 
EES modules is given below: | 


MODULE . SIZE | 
CLOCK | $c7-- Real-time-clock driver module 
BOOT $289 . Bootstrap module 


-DEBUG $7BB . Interactive DEBUG module 


- NOTE: The actual size of these modules may vary slightly. | 
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| TRE 05-9 RE M 


The 05-9 toe system is constructed from a number of 
Standard or user supplied modules selected to match a computer ^s 
hardware configuration. These modules are organized into a. 
hierarchical structure like the one below: | 


IOMAN 
f 
| 1 | 
R—— —— MÀ Ó— À—— —À—— ÓÁ— eae 
1 | E { 
l AE ! dd? { 
SCFMAN | RBFMAN SBFMAN ** - 
f ! * l 
pa ee pee opm puits l 
[^ l |. DISK ao TAPE © 
| | { i 
ACIA PIA ! | bo 
l ape ane aam aame dm he fm came amn ee memes oom de 
' { 1 ! 24 d l 
{ ! | ! | I i ! 
fp owe co ee m tmm d ^g 
! ! ! P | De Di TDS TDi 
! ! 


T1 P1 TERM 


The hierarchical organization makes it extremely easy to 


reconfigure or expand the I/O system, which is typically done by 


loading revised or additional modules into memory (they are 
automatically installed in the I/O system). | aus 


At the top level in the diagram, data is device independent and 
treated as if it were a stream of tytes. Data flowing vp from 
the device level is filtered by each module that it passes 
through, so that when it reaches the top, it will appear as a 
Stream of bytes and no longer be dependeat on the way it happened 
to come into the system. Lixewise, date flowing from the top 
down is “filtered” so that it will conform to any device 
dependencies; for exarple, the data may be blocked, os feeds 
may be inserted efter carriage returns, etc. ; 


* NOTE: SEFMAN 1S NOT CURRENTLY SUPFORTED BY MICROWARE 
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There are four levels of modules in the 05-9. I/O system as given 


below: 


1. 1/0 Manager (IOMAN). | | SCH 
2. File Managers (SCFMAN, REFMAN, SBEMAN) . 
3. Device Drivers (ACIA, PIA, DISK, etc.) ` 

4. Device Descriptors (TERM, D2, D1, etc.) 


TEE INPUT/OUTPUT MANAGER 


The Input/Output Manager (IOMAN) module provides the first 
level of service for 1/0 system calls by routing data on 1/0 
paths from processes to/from tne appropriate file managers and |. 
device drivers. It maintains two important internal 05-9 data. 


structures: the device table and the path table. This module is 
universal for all OS-S Level One systems and most users should 
never need to alter or replace it. | | 


FILE MANAGERS 


^ 0S-9 systems can have one or more File Menager modules. Tne 


function of a file manager is to process the raw data stream to 


or from the device drivers to conform to ine OS-9 standard file 
structure. -— l 


File managers usually buffer the data stream ard issue 
requests to the kernel for dynamic allocation of buffer memory. 


They may also monitor ard process the data stream, for example, 


adding line feed characters after carriage return characters. 


The file managers are reentrant end one file manager may. be 


used for an entire class of devices having similar operational 
characteristics. Standard 0S-S file managers are: 


RBFMAN: The Rardom Block File Manager which operates 
. random-access, block-structured devices such 
as disk systers, bubble memories, Etc. 


SCFMAN: Sequential Character File Manager which is used 
with Single-character-oriented devices such as 
CRT or hardcopy terminals, printers, modems, etc. 


SBFMAN: Sequential Block File Manager which drives block 
oriented devices that don't have random access 
capability, mostly tape systems. ger 


NOTE: SBFMAN IS NOT CURRENTLY SUPPORTED BY MICROWARE 


Most OS-9 systems will have two file managers: SCFMAN to 


handle terminals, and either RBIMAN (disk-based systems) or 
SBFMAN (tape-based systems). It is possible to use all three or 
more. Sophisticated users may wish to write their own special- 
purpose file managers. | l SE : | 
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“DEVICE DRIVER MODULES 


The device driver moëules contain a package of subroutines 
that perform raw 1/0 transfers to or from e specific type of 1/0 
device hardware controller. These modules are usually reentrant 
and one copy of the module can Simultaneously run several 
different devices which use identical I/O controllers. For 
example the device driver for 68°¢ serial interfaces is called 


“ACTA” and can communicate to any „number of Serial terminals. 
Provisions have been made so each incarnation of the driver can 
have its operational characteristics (such as paging, echo, 


backspace and delete characters, etc.) individually settable. 


Device driver modules use à standard. module header and are 
given a module type of "device driver (code $E). The execution 
offset address in ihe module header points to a branch table that 
has a minimum of six —(three-byte) entries.  Xacn entry is 
typically a  LBRA to the corresponding subroutine. The File 
Maregers call specific routines in the device driver through this. 
. tatle, passing a pointer to a path decriptor and the hardware 
control register address in the MPU registers. The tranch table 


looks like: — n 


A8 = Device Initialization Routine 
43 = Read From Device | | 

46 - Write to Device 

+9 = Get Device Status 
+50 = Set Device Status kee af 
+$F = Device Termination Routine 


For a complete description of the parameters passed to these 
subroutines see the file manager descriptions. Also see the 
appendicies on writing device drivers. 
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DEVICE DESCRIPTOR MODULES: 
| These small non-executatle rodules provide the system with 


the information. it needs to use ^a device. They associate a 
specific 1/0 device with its: . . | 


(a) Logical name. | | E 
(b) Hardware controller address(es). 
© (c) Device driver name. | 
(à) File manager name. | | 
(e) Initial operating parameters. 


Recall that device-.drivers anc file managers both operate on 
classes of devices, not specific devices. The device descriptor 
modules tailor their functions for a specific 1/0 device. One 
device descriptor module must exist for each logical. device in 
the 08-9 environment. ne. 


The name of tre module is the nare the device is known by to 
the system and user (i.e. it is the device name given in. 
pathlists)., Its format consists of a standard module header that 
has a type device descriptor (code $F). The rest of the device 
descriptor header consists of: . | | D B 

$9,$4 = File manager name string relative address. 
&B,$C = Device driver name string relative address. . 
© $D Mode/Capabilities (D 5 PE PW PR EWR) 
&E,$F,$10 = Device controller atsolute physical (24-bit) address. 
i11 = Number of tytes ("n^ bytes in intialization table) 
$12,$12+n = Initialization table | 


^ The initialization table is copied into the "option section | 
of the path descripter when a path to the device is opened. The 


values in this table Mey be used to define the operating 


parameters that are changeable by the 059 I$GSTT. and 1$SSTT 
Service requests. For example, @ terminal's. initialization 
parameters define which control characters are used for. 
backspace, delete, etc. The maximum size of initialization table 
which may be used is 32 bytes. If the table is less than 32 
bytes Long, the remaining values in the path descriptor will be 


set to zero. 


You may Wish to add additional devices to your system. If a 
similar device controller already exists, all you need to do is | 
add the rew hardware and load another device descriptor. Device. 
descriptors can be in ROM or loaded into RAM at aLy time. | 


The diagram on the next page illustrates the device descriptor: 
module format. Mad ings 
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The 03-8 i/0 System 


DEVICE DESCRIPTOR MODULE FORMAT 


+=- Sync Bytes ($87CD) sr. 


! | SEN 


po b 


ee? Module Size EE 
de 


o emm ams cm aum aum iuo. c» aa ee ón a E 


M | ! 


o +=- Offset to Module Name --+ 
l : L 


! $F (TYPE) p $1 (LANG) "t 
EE zs! Revision ! 


! Header Farity Check ! 


1 | A 


*—— Offset to File Manager “mt. 
(1c 3 Name String P 


+=- Offset to Device Driver --4 


! Nare String 4 
ade a cm am ae ee cee ao um oe ee — —!À un er oem aw v qua qs is ae p am e ne am el 
E Mode Byte ! 
TE a e e e ce ee + 
i l ! 
+e- Device Controller -— 


t Absolute Physical Address ! 


te (24 bit) -— 
! E: 


t Initialization Table Size ! 


A 


(Initialization Table) ! 
! ! 


bm anm cse iu, asm um. ap ger am gp amm duh UP am dio MT quB UND qu UE VE e HIP MP OU VID po qo t E 
! E 
t | (Name Strings etc) ! 
Doc S ) |i 
E DEE 


1 : A ! 


ue em zb 
E a CRC Check Value : ! 
dp em sam af 
ede tn am cmm eas cm uvm aem ats ame eins t sio m eut a P AR vum cum m ur v t t nn ee ome el 
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Below are the initialization table definitions for SCF and REF ` 


type devices: 


SCF DEVICE INITIALIZATION TABLE 
MODULE | | 


OFFSET ORG $12 
| TAELE EQU . , BEGINING OF OPTION TABLE | | 
$12 IT.DYC RMB 1 "DEVICE CLASS (@=SCF 1-RBF 2=PIPE 3=SBF) 
$13 IT.UPC RMB 1 CAS? (@=BOTH, 1=UPPER ONLY) ` 
$14 TP. .BSO RMB 1 BACK SPACE (G=BSE, 1=BSE,SP,BSE) 
o m DLO RMB 1 DELETE (£=285£ OVER LINE, 1=CX) 
$16 IT.EKO RMB 1 ECHO (£-NO ECHO) ` 7 Së 
$17 O IT.ALF RMB 1 AUTO LINE FEED (ð= NO AUTO LF) 
— $48 Te NUL RMB 1 END CF LINE NULL COUNT 
- $19 © IT.PAU RMB 1 PAUSE (£- NO END OF PAGE PAUSE) 
$14 IT.PAG RMB 1 LINES PER PAGE eke ee 
$18 — IT.BSP RMB 1 BACESPACE CHARACTER 
$10 IT.DEL PMB 1 DELETE LINE CHARACTER 
$1D IT.EOR RMB 1 END OF RECORD CHARACTER 
- $1E IT.EOF RMB 1 END CF FILE CHARACTER ) 
SIF IT.RPR EME 1 REPRINT LINE CHARACTER 
$280 . © DUP -RME 1 DUP LAST LINE CEARACTER 
$21 — Te, Dë EMB 1 PAUSE CHARACTER 
$22 IT.INT RMB 1 INTERRUPT CHARACTER | 
$23 IT.eQUT RMB 1 QUID CERRACIER ng, 
$24 Be Ga ISE RMB 1 BACKSPACE ECHO CHARACTER 
$25 1T.0VF. RMB 1 . LINE OVERFLOW CHARACTER (BELL) . 
$ 26 IT.PAR RMB 1 |INITIALIZATION VALUE (PARITY) 
$27 IT.BAU RMB 1 BAUD RATE E 
$28. IT.D2P RMB 2 ATTACHED DEVICE NAME STING OFFSET 
$2A ` SE RMB 2 RESERVED |— 
$20 IT. ERR RMB 1 INTITIAL ERROR STATUS 
NOTES: 
SCF editing functions will be “turned off” if the corresponding 
special character is a Zero. For example, if IT.EOF was a zero, 
there would be no end of file character. For a full description, 
please see the section of this manual on Sequential Character 
File Manager . SE AE | | | | 2 
1T7T.PAR is typically 


used to intitialize the device’s control 
register when a path is opened to it. SEN - a 
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REF DEVICE INITIALIZATION TABLE ` 


MODULE  - 

OFFSET ` | ORG $12 = 

812 IT.DTP RMB 1 DEVICE TYPE (@=SCF 1=RBF 2=PIPE 3=SEF) 
$132  jIT.DRV RMB 1 DRIVE NUMBER | e | ME 
$14. ^ IT:STP RMB 1 STEP RATE | S AE. 

$15 IT.TYP RMB 1 DEVICE TYPE (See RBFMAN path descriptor) 
$16 IT DNS RMB 1 MEDIA DENSITY (2 = SINGLE, 1=DOUBLE). 
$17 IT.CYL RMB 2 NUMBER OF CYLINDERS (TRACKS) e 
519 -IT.SID RMB 1 NUMBER OF SURFACES (SIDES) 

$14 IT.VFY RMB 1 Gs VERIFY DISK WRITZS 

S31B = IT.SCT HMB 2 Default Sectors/Track 

$105.65 IT.TCS RMB 2 Default Sectors/Track (Track £) 

$1F IT.ILV EMB 1 SECTOR INTERLEAVE FACTOR 

1 SEGMENT ALLOCATION SIZE 


. $26 IT.SAS RMB 


NOTES + 

IT.DRV This location is used to associate e ope byte integer ` 
with each drive that. a controller will handle. The 
drives for each controller should be numbered @ to N-1. 


 1T.5TP -This location sets the head stepping rate that will re, 


fastest value thet the drive is capable of to reduce 
access time. Below are the values which should te 


used: ` 

AN 

! FD1"771 ! PID1791, FD1797 ! 

STEP  +===== SE ii 
CODE ! $ ! 8 ! EE d 8 ! 
e o e —————————-— A a ee À— À——————— M + 

ð ! 4Brs | 1 céms d coms : 15ms E 

A a e ——— R—————————— fame ee ee EE + 

1 l 2215 { 12ms l 29 ms ! 12ms ! 
EE np marae meena spam me manne ee EES EE EE 

2 ! 12rs  ! 6ms ! 12ms  !  6ms i 


$- Y 12rs 1 Ems I .6ms to. ¿ms l 


The DC-2, DC-2, GMX #58 and BFD-68A controllers use the 
o FD1771 type chips. | 


The DF-2, GMY #23, GMX DMA, and DC$-4 controllers use 
the FD1791 or FD1797 type chips. SOR | 
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IT.TYP Device type 


" floppy disk 


tit g-- 6 = 
D 5" floppy diss 
bit 6 — Ø = Standard 95-9 format 
1 = Non-standard format 
vit 7 -- @ = Floppy disk | 
^. 4 = Hard disk. (may have smart controller) 


| IT.DNS Density capabilities 
single tit density 


bit o 2 = 
1 = Double bit density 
bit 1 -- @ = Single track density 
| 1 = Double track density | 
17.545 This value specifies the minimum number of sectors to 


be allocated at SE one EE 


For more information, please the section of this manual on  RBFMAN 
definitions of the path descriptor. 
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PATH DESCRIPTORS 


‘Every open path, „is associated with. a data structure. called a 


path descriptor ("PD"). It contains the information required by 


the file renagers and device drivers to perform I/O functions. 


Path descriptors are exactly 64 bytes long and are dynamically 


allocated and deallocated br LOHAN in response to requests from 


user programs. 


PIs are INTERNAL data structures. that are not normally 
referenced. from user or applications programs. In fact, it is 
almost impossible to locate a path’s PD when OS-9 is in user 


mode. The description of PDs is mostly of interest to, and 


presented here for those programmers who need to write custom 


file managers, device drivers, or other extensiors to 03-8. 


PDs have three E the first Ee sectionis defined 


universally for all file managers and device drivers. The second 


22-tyte section is reserved for and defined ty each type of, file 


manager. The last $Z-byte section is used as an “option” area 


for communications with user programs via the GETSTAT and SETSTAT 
system calls. The variables in this area are tyr pically used for. 


Qynamically-alterable operating parameters for the file or 


device. 

| Universal Path Descriptor Definitions 
Name Addr Size Description 
PD.PD $22 1 Path number | 
PD.MOD .50$- 3 Access mode: l=read 2=write S=update 
PD.CNT $02 = 1 Number of paths using this PD 
PD.DEV $23 2 Address of associated device tatle entry. 
PD.CPR $45 1 Reguester's process ID 
PD.RGS $26 2 Caller's MPU register stack address 
PD.BUF $98 2 Address of 256-tyte data buffer (if used) 
'PD.FST $A — 22 Reserved for file manager 
PD.OPT $20 . 32 


Reserved for GETSTAT/SETSTAT options 


For mere information, please see the sections of this manual on 


-file managers, device descriptors, and writing device drivers. 


. (C) 1989, 1981 Microvare Systems Corporation 


- PAGE 32 a 


/QS-9 LEVEL CNE SYSTEM PROGRAMMER/S MANUAL . 
The 0S-9 1/0 System — REFMAN $ 


RANDOM BLOCK FILE MANAGER 


The Random Block File Manager (RBFMAN) is the OS-9 module that 
supports random-access, block-oriented devices such as disk 
systems, bubble memory systems, and hign-performance tape 
systems. RBFMAN can handle any number or type of such systems 
simultaneously. It is a reentrant subroutine package called by 
IOMAN for I/C service requests to random-access devices. It is 
responsible for maintaining the legical and physical file 
structures. l 


In the course of normal operation, RAFMAN requests allocation ` 
ard deallocation of 256-byte data buffers; usually one is 
required for each open file. When physical I/O functions are 
necessary, RBFMAN | directly calls the subroutines in the 
associated device drivers. All data transfers are performed using 
256-tyte blocks . RBFMAN does not know about tracks, cylinders, 
etc. Instead, it passes the drivers a- logical sector number 
ranging from £ to n-1, where n is the maximum number cf sectors 
on the media. The driver is responsible for translating the 
logical sector number tc actual cylinder/track/sector values. | 


| Because RBFMAN is designed to support a wide range of devices 
having different performance and storage capacity, it is highly. 
^ parameter-driven. The physical parameters it uses are stored on 
the media itself. On disk systems, this information is written or 
the first few sectors of track number zero. The device drivers 
also use this information, particularly the physical parameters 
stored on sector @. These parameters are written by the "format ` 
program that initializes and tests the media. 


NOTE: IOMAN allocates a 64 byte path descriptor when a path is 


opened or createc, and deallocates the path descriptor after the 
path is closed. | ) 
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LOGICAL AND PHYSICAL DISK ORGANIZATION 


Identification Sector 


Logical sector number zero contains a description of the 
physical and logical characteristics of the volume. These are 
established by the "format command program when the media is 
initialized. the. table telow gives the 0$-9 mnemomic name, byte 
address, Size, and description of each value stored in this 
sector. 


D 
> 


name addr size | descrip tion 


` em gea TD E em: O AD E SD OAY GIE ve O, SIT em em OOP. TE S E gt MAER O SE vd R E SNE TD D wm em AUR ANUD at gf Am. (UND QUUD QuiP. NU of emm ef UAR. SEND ANIM. de n AMD. e EE CS A opp ge MED ER P MID. ES 


DD.TOT $90 5: Total number of sectors on media 

DD.TX5 174 L: Number of sectors per track e 
DD.MAP 504 Qu Number of bytes in allocation map 
DD.BIT $46 qe Number of sectors per cluster 

DD.DIR E ev. Starting sector of roct directory 
DD.OWN OB 2 Owner's user number . 

DD.ATT  $9D pos Disk attributes rw | 
DD.DSK $2E 2. Disk identification (for internal — 
DD.FMT $12 1 Disk format: density, number cf sides 
DD.SPT.. $11 2 Number of sectors rer track. 

DD. RES un e Reserved for future use npe pn 
DD.BT $15 ó Starting sector of bootstrap “file 
DD.BSZ $18 2 Size of bootstrap file (in bytes) 
DD.DAT SAA . 5 Time of creation: Y:M:D:H:M ` x 
DD.NAM .$1F 32 Volume name: last char has sign bit set 


Disk Allocation Map Sector , 


One sector cf the disk is used for the “disk allocation map" 
that srecifies which clusters on the disk are available for 
allocation of file storage space. The address of this sector is. 
always assigned logical sector 1 by the format program.  DD.MAP 
specifies the number of bytes in this sector which are EE 
used in the map. | | 


Each bit in the map corresponds to a cluster of sectors on the 
Ge sch number of sectors per. cluster is specified by tne 


“pp. BI?’ variable in the identification sector, and is always an . 


een power of twc, i.e., 1, 2, 4, 8, 16, etc. There are a 
maximum of 4296 bits in the mar, so media such as double-density 
double-sided floppy disks and hard disks will use 4 cluster size 


cf two or more sectors. Each bit is cleared if the corresponding. ` 


cluster is available for allocation, or set if tae sector is 
already allocated, non-existent, OF. physically defective. The 
bitmap is initially built by the format program. ` | | bi 
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File Descriptor Sectors 
The first sector of every file is called a "file descriptor’, 


"which contains the logical and physical descripticn cf the file. 
The table below describes tne contents cf the descriptor. e 


name addr size description 

FD.ATT $B. 1 File Attributes: D S PE PV PR EWR 
FD.OWN $1 2 Owner's User ID ` | 
FD.DAT Z 5 Date Last Modified: Y M" DEM 
FD.LNÉ $8 1 Link Count 

FI.SIZ . $9 4 File Size (number of bytes) 

FD.DCR $D T Date Created: YMD 

FD.SEG $10 240 . 


Segment List: see below 


The attribute byte contains the file permission tits. Bit 7. 
is set to indicate a directory file, bit 6 indicetes e sharable- 
file, bit 5 is public execute, bit 4 is public write, etc. ME 


The segment list consists cf up to 48 five-tyte entries that 
have the size and address of each block of storage that comprise 
the file in logical order. Each entry has a three-byte logical. 
sector number of the block, end a twe-byte block size (in 
'sectors). The entry following the last segment will be zero. ` 


When a file is created, it initielly has no data «segments Do o 


allocated to it. Write operations past the current end-of-file 
(the first write is always past the end-of-file) cause additional. 
sectors to be allocated to the file. If the file has no 


“segments, it is given an initial segment. having the number of .. 


sectors specified by the minimum allocation entry in the device 
descriptor, or the number of sectors requested if greater than 
the minimum. Subsequent expansions of tae file are also generally 
"made in minimum allocation increments. An attempt is made to 
expand the last segment wherever possible rather than adding a 
new segment. When the file is closed, unused sectors in. the last 
. Segment are truncated. 


A acte about disk allocation: 05-9 attempts to minimize the 
number of storage segments used in a file. In fact, many files 
will only have one segment in which case no extra read operations ` 
are needed to randomly access any byte on the file. Files can 
have multiple segments if the free space of the disk becomes very 
fragmented, or if a file is repeatedly closed, then opened and ` 
expanded at some later time. This can be avoided by writing a 

byte at the highest address to be used on a file before writing 
any other data. l | a | | 
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O Directories | 
Disk directories are files that have the D bit set in their 
attribute byte. Each directory entry is As bytes long, ` 
consisting of 29 tytes for the file name followed by a three byte 
logical sector number of the file’s descriptor sector. The file 
name is left-justified in the field with the sign bit of the last 
character set. Unused entries have a zero byte in the first file 
rame character position. Every mass-stotage media must, have at 
least one master directory called the root directory . The 
beginning logical sector number of this directory is stored in. 
the identification sector, as previously described. 


RBFMAN Definitions of the Path Ee 
The table below describes the usage of the file-manager- 


reserved section of rath descriptors used by RBFMAN. Also see 
the section of this manual on path descriptors. | 


Name Addr Size Description 


C |». Universal Section ` 
»PD.PD $88 1 Path number 
PD.MOD $91 °° 1 pode (read/write/update) 
PD.CNT $22 E: Number of open images 
PD.DEV $23 2 Address of device table entry 
PD.CPR $05 1 Current process ID 
PD.RGS $96 2 Address of callers register stack 
PD.BUF $98 2 Buffer address | 


RBFMAN Path Descriptor Definitions 


PD.SMF SEA 1 State flags (see next page) ` 

PD.CP $23 4 Current logical file position (byte addr) 
PD.SIZ $ØF 4 File size | 
PD.SBL $13 3 Segment beginning logical sector number 
PD.SBP $16 3 Segment beginning physical sector number ` 
PD.SS2 $19 2. Segment size 

PD.DSK e A^ Lisk ID (for internal use only) 

PD.DTS 1D 2 Address of drive table 


(continued) 
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N EEFMAN Option Section Definitions 


Device class Oe SCF 1=RBF 2-PIPE  3=SBF. 


SÉ "Gap 1 

PD.DRV $21 1 Drive number (€..N) 
PD.STP $22 1 Step rate 
PD.TYP $23 1 Device type ` 
PD.DNS $24 p Density capability 

-~ PD.CYL $25 2 Number of cylinders (tracks) 

.UPD.SID $27 i Number of sides (surfaces) | 
PD.VEFY $28 1 Q = verify disk writes | 
 PD.SCT $29 2 Default number cf sectors/track | X i 
PD.T2S $25 2 Default number of sectors/track (track @) ` 
PL.ILY E 1 Sector intreleave factor | | | 
TD.SAS $23 i Segment allocation size E 


(the following values are NOT copied from the device descriptor) 8 


PD.ATT $33 1 File attributes (D S PE PW FR X W R) | | 
- PD.FD $34 3 file descriptor PSN (physical sector #) | 
< PD.DFD $3" 3 Directory file descriptor PSN : | 
PD.DEP $3A 4 File’s directory entry pointer 

PD.DVT SSE 2 Address of device table entry 

State Flag (PD.SMF): the bits of this byte are defined as: 


* 
AG vit @ = set if current buffer nas been altered 
EE oO bit 1 = set if current sector is in buffer 
| “pit Z= set if descriptor-sector in buffer 


The first section is universal for all file managers, the second ES 
and third sections are specific for RBFMAN and REFMAN-type device ` 
drivers. The option section of the path descriptor contains many 
device operating parameters which may be read and/or written by 
e « the OSS I$GSTT and 1$SSTT service requests. This section is. 
initialized by IOMAN whe copies tae initialization table of the 
device descriptor into the option section of the rath descriptor 
when a peth to 4 device is opened. Any values net determined by 
this table will default to zero. NEE | | | 


t 


NOTE: For a description of the values copied into the option | 
section of the path descriptor and other related information, - 
please see the Section of this manual on device descriptors. | 
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terminals, printers, modems, etc. 


type 


th 
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called by I 


oriented devices. 
editing functions typical of 


 backSrace, 


pause, return 
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 SEGUENTIAL CHARACTER FILE MANAGER ` 


File Manager (SCFMAN) is the 05-9 
character-oriented ` devices such as 
SCFMAN can handle any number or . 
uch systems. It. is a reentrant subroutine package 
OMAN for 1/0 service requests to Sequential character 
It includes the extensive input and output 
line-oriented operation such as: 
line delete, repeat line, auto line feed, Screen 

delay padding, etc. 


at supports 


-SCFMAN Definitions of The Path Descriptor 


The table below descrites the 
and SCFMAN-type device drivers. 


path descriptors used by SCFMAN 
Also see the section of this 


manual on path descriptors and device descriptors. 


Universal Section 


PD.PE soo 
PD.MOD $81 
- PD.CNT 155 
PD.DEV os 
-= PD.CPR $85 
PD.RGS | $06. 
PD.BUF $28 
SCFMAN Path 
PD.DV2 $04 
PD.RAW  $92C 
PD.MAX Gut 
PD.MIN $4807 
(continued) 


Path number 

Mode (read/write/update) 

Number of open images 

Address of device table entry 

Current process ID 
Address of callers MPU register stack 
Buffer address 


NM NR eb 


Descriptor Definitions 


2 Device table addr cf 2nd (echc) device 
1 Bait flag: @=Taw mode, isedit mode | 
2 Readline maximum character count 

1 Devices are mine if cleared 
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SCFMAN 


PD.UPC. 


PD.BSO 


PD.EKO 
PD.ALF 
NUL 
PL.PAU 
PD.PAC 
PD.ASP 
PD.DEL 
PD.EOR 


PD.EOF 


PD.RPR 
PD.DUP 


PO.PSG 
—PD.INT 
-PD.CUT 

PD.BSE 


PD.OVF 
PD.PAR 
PD.BAU 


PD.D2P ¿ 
WER 


PD.TBL 


The first section is universal for all file. managers, the 
third section are 
drivers. The option section 


and 


device 


OS9 ISGSTT or ISSSTT service requests. 
section when a 
corresponding device descriptor initializetion table. 


not determined by this 


Srecial 


OS-9 LEVEL ONE SYSTEM PROGRAMMER/S MANUAL 


: The 05-8 I/O System — SCFMAN 


option Section Definition 


$2€ 
$21 


$22 


¿23 
$24 
$25 
$26 
$27 
$28 
| $28 
¿24 
¿2B 
$2C 


NENN FRR PRP REPRE HE EE 


Device class. ge SCF 1-RBP 2=PIPE 3= SBF 
Case (PsBOTA, 1#UPPER ONLY) - | 
Backsp (B-BSF, 1=BSE SP BSE) 

Delete (DG = ESE over. line, de CR Lei 
Echo (Bsno echo) 

Auto LE (®=no auto LP) 

End of line null count 

Pause (£- no end of page pause) 

Lines per page . | | 
Backspace character 

Delete line character 

End of record character (read only) 
End of file character (read only). 
Reprint line character 

Duplicate last line charecter 

Pause character A, 
Keyboard interrupt character (TL D) 
Keyboard abort character (CTL 0) 

| Backspace echo character (BSE) 

Line overflow character (bell) 

Device initialization value (parity) 
Software settatle baud rate 


Offset to 2nd device name SE 
Reserved for future use 
Accumulated 1/0 error status. 


| Address of device table 


second 
specific for SCFMAN and SCFMAN-tyve device 
of the path descriptor contains many 


operating parameters which may te read cr written by tne 


editing. functions | 
corresponding control character value to zero. 


peth 


(C) 1982 


M 


IOMAN initializes this 
device by copying the. 
Any values. 


is opened to a 


PERPE will Seran to zero.. 
be setting the 


may DEE DY 
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SCFMAN Line Editing Features 


ISREAD and I$WRITE service | requests to .SCFMAN type devices 
generally pass the date to/from the device | without. any ` 
modification, except that keyboard interrupt, keyboard abort, and -. 
pause character are filtered out of the input (editing is 
disabled if the corresponding character in the path descriptor 


contains a zero). In particular carriage returns are not 


autometically followed ty line feeds cr. nulls, and the high order. 


bits are passed as sent/received. 


i . . | . 
I$RDLN and ISWRLN service requests to SCFMAN type devices po 


cause the following editing to occur: 
All bytes input or output have their high order tit cleared. 


If PD.UPC <> @ bytes input or output in the range "a..z" are 
made A..Z | 


If PD.EKO <> Z, input bytes are echoed, except that | 
undefined control characters in the range 52..51F print as 


e 


If PD.ALF <> 9, carriage returns are automatically followed 
by line feeds. 


If PD.NUL <> 9, After each. Sien a PD. NUL "nulls" (always 
$00) are sent. ` | 


1? PD.PAU <> Ø, Auto page pause will occur after every 
PD. PAU lines since the last input. .- | Zb 


If PD.BSP o a SCF will recognize PD.BSP as the EE 
backspace character, and will echo PD.BSE (the backspace 
echo character) if PD.BSO = 2, or PD.BSE, space, PD.BSE if 
PD.BSO <> 0. | - 


If PD.DEL <> @, SCF will recognize PD.DEL the delete line 
character (on input), and echo the "backspace Sequence over 
the entire line if PD.DIO = 2, or echo CR/LF if PD. DIO <> € 


PD.EOR defines the end of record character. This is the 
last character on each line entered (ISRDLN), and terminates 
the output inr when this character is sent. Normally. 
PD.EOR will. set to $@D. If it is set to zero,. SCF's 
READLN will Be terminate, unless an ECF occurs. 


If PD. EOF <> 0,. it defines the end of fil character. 
SCFMAN will return an end-cf-file error oa IS READ or ISRDLN 
if this is the first (and only) character input. It can be 
disabled ty. setting its value to zero. 


If PD.RPR > 2, SCF (ISRDLN) ill, upon receipt cf is 
character, echo a carriage return [oz tional line feed], and 
then: reprint the current line. a UR 
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1f PI.DUP <> @, SCF (ISRILN) will duplicate whatever is in 
the input buffer through the first PD.EOR character. 


If PD.PSC <> £, cutput is suspened before the next  "PL.FOR' 
character when this ‘character is input. This will also. 
delete any type ahead input for ISRDLN. | | 


If PD.INT <> @, and it is received on input, a keyboard 
interrupt signal is sent to the last user of this path. 
Also it will terminate the current I/O request (if any) with 
an error identical to the keyboard interrupt signal Code, 
This location normally is set to a control-C character. 


If PD.QUT <> @, and it is received on input, a keyboard 
abort signal is sent to the last user of this path. Alse it 
will terminate the current 1/0 request (if any) with an 
error code identical to the keyboard interrrupt signal code. 
This location is normally set to a control-Q character. 


If PD.OVF <> £, It is echoed when ISRDLN has Satisfied its 
input byte count without finding a PD.EOR character. 


NOTE: It is possible to disable most of these special editing 
functions by setting the corresponding control charécter in the 
path cescriptor to zero by uSing the I$SSTT service request. A 
more "permanent soluticn may be had by setting the corresponding 
control character value in the device descriptor to zero. 


Device descriptors may be inspected to determine the default 
settings for these values. E 
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‘INTERRUPT PROCESSING © 


The 0S-9 kernel ROMS contain the hardware vectors required ty 
the 6809 MPU at addresses $FFFO through $FFr¥. These vectors 
each point to jump-extended-indirect instruction which vector the 
MPU to the actual interrupt service routine. A RAM vector table 
in page zero of memory contains tae target addresses of the jump 
instructions as follows: se e 


INTERRUPT ADDRESS 
SWIS | 5902C 
SWI2 $0023 
FIRQ 39030 
IRQ NE $9932 
SWI 30234 


NMI ` i $9036 


0S-9 initializes each of these locations after reset to point to 
a Specific service routine in tne kernel. The SWI, SWI2, and 
SWI3 vectors point to specific routines which in turn read tne 
corresponding pseudo vector from the process” process descriptor 

and dispatch to it. This is why the F$SSWI service request to te 
local to a process since it only changes a pseudo vector in tne 
process descriptor. The IRO routine points directly to the IRQ 
polling system, or to it indirectly via the real-time clock 
device service routine. The FIRQ ard NMI vectors are not 
normally used by 03-9 and point to RTI instructions. | 


A secondary vector table located at $FFEQ contains the addresses 


of the routines that the EAM vectors are initialized to. They 


may be used when it is necessary to restore the original service 
routines after alterirg the RAM vectors. On the next page are 
the definitions of both the actual hardware interrupt vector 
table, and the secondary vector table: 
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N 08-9 Interrupt Vector Tables 


VECTOR ADDRESS 


0$-9 Secondary Vector Table 


TICK ' poe Clock Tick Service Routine 
SWIS $YFEZ2 | | | 

SWI2 SFFE4 

FIRQ Terre 

IRQ FFEB- 

SWI SFFEA 

NMI ` |. S$FFEC | SH 

WARM | SFFEE Reserved for warm-start 


Actual Hardware Vector Table 


EVA 3333 
SWI2 $FFF4 
FIRQ $FFF6 
IRQ ¿FFF8 
SVI $FFFA 
NMI SFFFC 


RESTART SFFFE 


If it is necessary to alter the RAM vectors use the secondary 
vector table to exit the substitute routine. The technique of 
altering the IRQ pointer is usually used by the clock service 
routines to reduce latency time of this frequent interrupt 
source. | Š | | 
d 
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IRQ AUTOMATIC POLLING SYSTEM 


In 0S-9 systems, most 1/0 devices use IBG-type interrupts, an ` 


OS-9 includes a sophisticated polling system that automatically 


identifies the source of the interrupt and dispatches to its 


associated user-defined service routine. The information 


required for IRQ polling is maintained in e data structure called ` 
the IRQ polling table’ . The tatle has a S-byte entry for eaen. 

possible IRQ-generating device. Tae tatle size is static and 
defined by an initialization constant in tae System Configuration 
Module. : | 


The polling syster is prioritized so devices having a 


relatively greater importance (i.e., interrupt frequency) are 


polled before those of lesser priority. This is accompli shed by 
Keeping the entries sorted a ity, which is a number between 
g (lowest) and 255 (highest) Each entry in the table has 6 


“1. POLLING ADDRESS: The address of the device’s status register, 


which must have a bit or bits that indicete it is the source 
of an interrupt. 5 ad 


2. MASK BYTE: This byte selects one or more tits within the 
. device status register that are interrupt reguest flag(s). A ` 
set bit identifies the active bit(s). | 


de FLIP BETAS This byte selects whether the bits ir the device 


Status register are true when set or true when cleared. 
Cleared bits indicate active when set. | | ne 


4. SERVICE ROUTINE ADDRESS: The user-supplied address of the 
device’s pacer EE. service routine. | MESS 


.5. STATIC STORAGE ADIRESS: a user—-Supplied pointer to the 


permanent storage required ty the device service routire. 


6.. FRIORITY: ME derice priority number: © to 255, This value 


determines the order in. which the devices in the polling 
table will be polled. Note: this is not the same as a 
process pricrity which is used by the execution scheduler te 
decide which process gets the next time slice for MPU 
execution. | | 


“hen an IRQ interrup t occurs, tne polling system is entered 
via the corresponding RAM interrupt vector. It starts rolling 
the. devices, using the entries ir the polling table in priority 
order. For each entry, the status register eddress is loaded 
into ue cumulates à using the device address from the table. An 
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exclusive-or operation using the  flip-byte . is executed, 


followed ty a logical-and operation using the mask byte. If tane 


result is non-zero, tae device is assumed to be tne. cause of tne | 
interrupt. The device’s static storage. address and service 
routine address is read from the table, and jumped to. E 


NOTE: The interrupt service routine should terminate with an 
RTS - NOT AN RTI instruction. 


-Entries can be made to the IRQ polling tebie by use of a 
special OS-9 service request called "PS1IRQ + This is a 
priviledged service request that can be executed only when 0S-9 . 
is in System Mode (which is the case when device drivers are 
executed). 
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WRITING INTERRUPT-DRIVEN DEVICE DRIVERS 


It is important to understand that interrupt service routines 
are asynchronous and somewhat . nebulous in that they are not ` 
distinct processes. In fact, when they are invoked ANY 
indeterminate process may have been interrupted, but not 
necessarily the process that triggered the interrupt-causing 
event. | | e? | : | 


Therefore, all interrupt-driven device crivers have two tasic 
parts: the mainline Subroutines that execute as part of tne 
calling process, and a separate interrupt service routine. ` 


TEE TWO ROUTINES ARE ASYNCHRONOUS AND TRESEFORE MUST USE SIGNALS 
FOR COMMUNICATIONS AND COORDINATION. 


The INIT initialization subroutine within the driver package 
should allocate static storage fcr the service routine, get the 
service routine address, and execute the F$I39 system call to add 
it to the IRQ polling table. kd 


When a device driver routine does something thet will result 
in an interrupt, it shovld immediately execute a  F$5LEP service 
request. ^ This results in the process” deactivation. When the 
interrupt in question occurs, its service routine is executed 
after some random interval. It should then do the minimal amount 


of processing required, and send a wakeup signal tc its | 


D 


associated process using tae F$SZND service request. It may also 
put some data in its static storage (I/9 data and status) which 
is shared with its associated sleeping process. 


Some time later, the device driver "meinline" routine is 
awakened by the signal, and can process the data or status 
returned ty the interrupt (service routine. Remember that. 
processes that execute sleep requests while in system State are 
given maximum priority by the scheduler. | 

| f 
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WRITING C5-9 ASSEMBLY LANGUAGE PROGRAMS. 


There are four key rules for programmers writing 0S-3 assembly 
language programs: 


4. All programs MUST use p esition-independent=code. (PIC). E 
selects load addresses based- or available memory at run-time 
There iS ro way to force a program to be loaded at a specific 
address. vi T | 


2. Programs must be orgenized as contiguous memory modules, 
which are the OS-9 equivalent of load records . 


3. Storage for variables ard data. structures must be “part of the 
data area which is assigned by 05-2 at run-time, and is seperate 
from the program module (section). 5 | | 


4. All input and output operations shouid be made nis 0S-9 
service request calls. ` = 


Fortunately, the 6899°s versatile addressing modes make the rules 
atove easy to follow. The Ge? essembler also helps because it 
has dran capabilities to assist the programmer in creeting 
programs for the OS-S execution environment. 


Using ———: 


It is simple to write Gags Position-indepen&ent- -cede (PIC). 
The trick is to always use PO-relative. addressing; for example: 
BRA, LBRA, BSR and LBSR. Get addresses of constants and tatles 
using LEA instructions instead of lead immediate instructions. 
If you use dispatch tables, use tables of RELATIVE, nct absolute, 
addresses. 


INCORRECT | CORRECT 


LDX #TABLE LEAX TABLE,PCR 
JSR SUBR ESR SUBR or LBSR SUBR 


Standard Input/Output Paths 


Programs should be written to use Standard I/O paths gë 
(input), #1 (output), and #2 (error output) wnerever practical. 
Usually, this jinvolves 1/0 calls that are intended to communicate 
to the {user's terminal, or any other case where the 05-9 
redirected 1/0 capability is desirable. These patis do not have 
to be oP E or PRESSE Yo S ME E 
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How to Select Addressing Modes ` 


|. Programs to be invoked using FORK and CaAIN system calls nave 
RAM memory assigned at execution-time. ` The addresses cannot te 
known or specified ahead of time. Again, thanks to the 68%9s 
full compliment of addressing modes this presents ro problem. 


When the program is first entered, the Y register will have 
the address of the top of your data memory erea. If the creating 
process passed a parameter area, it will te located from. the 
value of tne SP to the top of memory (Y), and tae D register will 
contain the parameter area size in bytes. If the new process was 
called ty the shell, tne parameter area will contain the part of 
the shell command line that includes the argument (parameter) 
text. The U register will have the lower bound of the data memory 
area, and the DP register vill contain its page number. 


The most important rule is to NOT USE EXTENDED ADDRESSING! 
Indexed and direct page addressing should be used exclusively to 
access data area values and structures. Lo not use program- 
counter relative addressing to find addresses in the data area, 
but do use it to refer to addresses within tre program aree. 


The most efficient way tc handle tables, buffers, stacks, 
etc., is to have the program’s initialization routine compute 
their absolute addresses using the data area. tcunds passec ty 
OS-9 in the registers. These addresses can then te saved in the 
direct page where they can Dë loaded into registers quicily, 
using snort instructions. 


This technique has advanteges: it is faster then extended 
addressing, and the program 1s inherently reentrant. | | 


Machine Stack Requirements 


Because 0S-9 uses interrupts extensively, arc also because 
many reentrant E629 programs use the MPU stack for local variable 
storage, a generous stack should be maintained at all times. The 
recorrended minimum is approximately 22U bytes. kx | 


Interrupt Masks 


User programs should keep the condition coies register 3 (FIRE 
mask) and I (IRQ mask) tits off. They car te set durirg critical. 
program sequences to avoid task-switching or interrupts, but this 
time should be xept to a mimimum. If they are set for longer. 
than a tick period, system timekeeping accurecy will te affected. 
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Example Program. 


The example program shown below 
how 
program will print 
for a line to be typed in. 


idea 


se 


as 


to 


NAM 
OPT 


USE 


— /D0/2 


adéres 
EELIO 


EXAMPLE 
-M 


AMMERS MANUAL 
e Progrems. | 


some. | 


is preserted nere to provide 
sing modes etc. are actually used. - ihis 


WOELD' on the terminal, erd tanen- 


EFS /OSSDEFS 


: 0S-9 System Definition File Included 


LINLEN 
INPBUF 


STACK 
DATMEM 


- NAME 
ENTRY 


ERROR 


OUTSTR 
STRLEN 


ENDPGM 


NOTE: The OSODEFS system defin 


ORG 
RMB 
RMB 


RMB 
. EQU 


EQU 


MOD 


FCS - 
ECU 
LEAX 
LDY 
LIA 


. 0S9 


BCS 
LEAX 
LDY 
LDA 
089 
BCS 
STY 


CIRE. 


059 


FCC 


FCB 
EQU 


EMOD 
EQU 


g 


e 


sg 
220 


ed 


* 


SAVE LINE LENGIE EERE 
LINE INPUT BUFFER | 
MINIMUM HARDWARE STACK SIZE |. 


DATA AREA MEMORY SIZE 


ENDPGM,NAMF ,OBJCT+PRGRM,REENT+1, ENTRY ,DATMEM 


/ EXAMPLE / 
x^ 


OUTSTR,PCR 
#STRLEN 

#1 

ISWRLN 
ERROR 
INPBUF,U 


ERROR ` 
LINLEN 


FSEXIT 


/EELLO WOR 
$ OD 
*-OUTSTR 


Se 


0S-9 . assembler. Also 
directory than the one 
program. | 


(0) 1984, 


given in the 


MODULE NAME STRING : A 
MODULE EXECUTION ENTRY POINT 
GET ADDRESS OF OUTPUT STRING | 
org STRING LENGTE ` S 
SPT STANDARD OUTPUT PATH NUMB. 
WRITE THE LINE 
BRA IF ANY 1/0 ERRORS OCCURED 
GET ADDR OF INPUT BUFFER | 
INPUT MAX OF 82 CHARACTERS 
GET STANDARD INPUT PATE NUMBE 
READ THE LINE INTO THE BUFFER 
BRA IF ANY 1/0 ERRORS OCCURED 
SAVE TEE LINE LENGTH : 
RETURN WITH NO ERRORS 
TERMINATE TEE PROCESS 


LD/ OUTPUT STRING. 
END OF LINE CHARACTER 
STRING LENGTH — 


END OF MODULE ` 
END OF PROGRAM 


itions file is supplied with tne 
this file may be located in a differert 
USE statement in tne 
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OS-G SERVICE REQUEST DESCRIPTIONS 


System calls are used to communicate between the -05-S operating 
system and assembly-language-level programs. There are three 
general categories: | | ! du | | 


1. User mode functicn requests 
2. System mode function requests 
3. I/0 requests : | | 


System mode fuction requests are priviledged and mey te executed 
only while 0S-9 is in the system state (when it is. processing 
another service request). They are inciuded in this manual 
primarily for the tenefit of those programmers who will be 
writing device drivers and other sophisticated applicaticns. 


The system calls are performed ty loading the MPU registers with 
the appropriate parameters (if any), and executing a WIZ 
instruction immediately followed by a constant byte which is the 
request code. Parameters (if any) will te returned in -the MEU 
registers after 05-9 has processed the service request. A 
standard convention for reporting errors is used in ail system 
calls; if an error occured, the C bit of the condition code 
register will be set and, accumulator B will contain the 
appropriate error code. This permits a BCS or BCC instruction 
immediately following the system call to branch on rror/no 
errror. 6° ues ) 


Here’s an example system call for the “CLOSE” service request 
(code $823): 


. LDA PATHNUM 
| SWI2Z 
SCH $8B 
BCS ERROR 


“Using the assembler’s "0S9" directive simplifies the call: 


LDA PATHNUM 
OSS I$CLOS 
. BCS ERROR 
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The 1/0 service requests are simpler to use than in many other 
operating systems because tae calling program does not nave to 


allocate and set up “file control bloczs”, "sector buffers”, etc 
Instead OS-9 will return a one byte path number when a path to à 


file/device is opened or created; then this path number may be . 
used in subsequent 1/0 requests to identify the file/device 
- until the path is closed. 05-9 internally allocates and 


maintains its own data structures and users never have tc deai 
with them: in fact attempts to do so are memory violetions. 


All system calls have à mnemonic name that starts. with QE for 


system functions, or ‘I$ for 1/0 related requests. These are. 


defined in the assembler-input equate flle called OSSDEFS . 


In the service request descriptions which follow, registers not 
explicitly specified as input or output parameters are not 


altered. 


Strings passed as parameters | are normally terminated by having 
bit seven of the last character set, a Space character, or an end 
of line CESTO Cien: | 


(C) 1980, 1981 Microware Systems Corporation 
- PAGE 51 = 


wm — A a wa ~ omen a mme mo + rm ` wma ie NE e oce men 


CH PROGR AMER^S MANUAL 


ET ABIT ` - Set bits in an al location pit map 2 O FÉABIT | 


ASSEMBLER CALL: | 059 FSARIT 
MACHINE CODE:  183F 13 
Base address of allocation pit map, 


Bit number of first bit to set. 


INPUT: Ss 
(D 
Bit count (numter of bits to set). 


(Y) 
OUTPUT: None. 


bit set. 


FRROR OUTPUT: 
e error code. 


i C 


This system mode service Peousst sets bits in the allocation bit 
map specified by the X register. 


Bit numbers Tange from £..N-1, where N is the number of bits in 
the allocation bit mar. | | 


C) 
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CHAIN Load and execute a new primary. module. = SEH 


ASSEMBLER CALL: 059 F$CHAN — 


MACHINE CODI: 103F BE ` 


Address of module name or file name. 
Parameter area size (256 byte pages). 
Beginning address of parameter area. 
Language / type code. 

"Optional data. area size (256 tyte pages). 


H d nw M 


(X) 

(Y) 

(U) 
de AS 

(3) 


ERROR OUPTPUT: (CC) = C bit set. 


(8) = Appropriate error code. 


this system Geer is similar to FORK, put it does not create a new ` 
. process. It effectively ‘resets’ the calling process” program 


and data memory areas and begins execution of a new primary 
module. Open paths are not closed or otherwise affected. 


This system call is used when. it is necessary to execute an. 
entirely new program, but without the overhead of creating a new 
process. It is functionally similar to a FORK fcilowed by an 
EXIT, but with less processing overhead. ` 


The sequence of operations taken by CHAIN is as follows: . 


1. The system parses the name string of the new process” 
"primary module - the program that will initially be executed. 
Then the system module directory is searched to see if a module 
with the same name and type / language is already in memory. If 
so it is linked to. If not, the name string is used as the 
pathlist of a file which is to be loaded into memory. Then the 
first module in this file is linked to (several modules may. have 
been loaded from a single file). | | 


2. The process” olà primary moduie is UNLINKED. 


3. The data memory area is EL Re to the size specified. 
in the new primary module” S header. — EM 


/ 
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CHAIN (continued) 


The diagram below shows how CHAIN sets up the data memory area 
and registers for the new medule. | 


HE EO EE == e ed. 

i i 

! i 

(4 parameter i 

i area H 

d | dë 
pom mmm (rr X, SP 

| po 
Dos 4 i 

! { 

! data area i 

| | 

i H 

[ . 1 
` rp ame —ÀÀ aoe ama E. 

| direct page i 

Aen eme re S DP 
D = parameter area size 
PC = module entry point abs. address 
CC = F=8, 1=9, others undefined 


Y (top of memory er) and U (bottom of memory ohter? will 


always have a values at 25€-byte page boundaries. If the parent 
does not srecify a parameter area,. Y, X, end SP will be the same, 
and D will equal zero. The minimum ‘overall data area size is one 


| .pege (256 SESCH 


WARNING: The hardware stack pointer (SP) should be located 


somewhere in the direct page before the FSCHAN service request is 


executed to prevent a suicide attempt error or an acutal 


suicide (system crash). This will prevent à suicide from 


occuring in case the new mcdule requires a smaller data area than 
what is currently being used. You should allow approximately <06 


tytes of stack space for execution of the FSCHAN service EE 
and oiner system ‘overhead. 


For more information, please see the F$FORK service request 
EE . 
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ur Wie. Mam MT MM ma 


COMPARE NAMES Compare two names. ^ — |  P$CNAM 


“ASSEMBLER CALL: 0S9 FSCNAM 


MACHINE CODE: 123F 11 


INPUT: (X) = Address of first name 
— (B) = Length of first name. 
(Y) » Address of second name. 
OUTPUT: (CC) = C bit clear if the strings match. 


Given the address and length of a string, and the address of a 


second string, compares them and indicates. whether they match. 


Typically used in conjunction with “parsename . 


The second name must have the sign bit (bit 7) of the last 
EE set. He dt | er a 


H 
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INPUT: (x) 
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CRG. AE A Compute CRC | | CUN EIERE 


ASSEMBLER CALL: 059 F$CRC 

MACHINE CODE: 123F 17 

= Starting byte address. 

Y) = Byte count. 

(U) = Address of 3 byte CRC accumulator. 
OUTPUT: CRC accumulator is updated. 


ERROR OUTPUT: None. 


This service request calculates the CRC. {cyclic redundancy count) 


for use by compilers, assemblers, or other module generators. 


The CRC is calculated starting at tne source address over byte. . 
count bytes. It is not necessary to cover an entire module in 


one call, since the CRC may be ‘accumulated over several cails. 


The CRC accumulator must be initialized to SFFFEFF before the 
. first Beene call. SW e 


The last three bytes in the module MUST be | $PPFFFF. This is the 
initial module CRC and is normally replaced DY the calculated 


value. 
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DBIT _Deallocate in a bit map NEE td 


ASSEMBLER CALL: 089 FSDBIT 
MACHINE CODE: ~ 103F 14 
Base address of. an Ee on bit map. 


Bit number of first bit to clear. 
Bit count (number of bits to clear). 


INPUT: (X) 


y 
d 


OUTPUT: None. 


C tit set. 
Appropriate error code. 


ERROR OUTPUT: 


This system mode service request is used to clear bits in the 
allocation bit map pointed to by X. | 


Bit numbers range from £..N-1, where N is the number of bits in 
the allocation tit map. | 
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weg: A auge mph qm 


EXIT. = o Terminate the calling process. eS gts FSEXIT 


ASSEMBLER CALL: OS9 FSEXIT e 


MACHINE CODE: 103F 06 


INPUT: (B) = Status code to be returned to the parent process. 


QUTPUT: Process is terminated. 


This call kills the calling process. Its data memory area is 
deallocated, and its primary module is UNLINKed. All open paths 
are automatically closed. | = d 


The death of the process can be detected by the parent executing 
a WAIT call, which returns to the parent the status byte passed 


py the child in its EXIT call. The status byte can pe an OS-9 


error code the terminating process wishes to pass tack to its 
parent process (the shell assumes this), or can be used tc pass a 
user-defined status Value. Processes to be called directly by 
the shell should only return an 08-9 error code or zero if no. 
error occurred. ) 2 En 
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FORK Create a new process. — le ea SPORE 


ASSEMBLER CALL: OS9 FSFORE 


. MACHINE CODE: 103F 23 


Address of module name or file name. 


INPUT: (xX) = 
. (Y) = Parameter area size. | | 

(U) = Beginning address of the parameter area. 
(A) = Language / Type code. | | | 
(3) = Optional data area size (pages). 

OUTPUT: (X) = Updated path the name string. 

| (A) = New process ID number. 
ERROR OUTPUT: | (CC) = C bit set. 


(B) » Appropriate error code. 


This system call creates a new process which becomes à "child" of 
the caller, and sets up the .new process’ memory and MPU. 
registers. ps e : . x | 


The system parses the name String of tLe new process” primary 
module’ - the program that will initially be executed. Then the 
system module directory is searched to see if the program is 
already in memory. If sc, the module is linked to and executed. 
If not, the name string is used as the pathlist of the fiie which 
is to be loaded into memory. Then the first module in this file 
us linked to and executed (several modules may have been loaded 
from a single file). | | | 


The primary module’s module header is used to determine the 
process” initial data area size. 05-9 then attempts to allocate 


4 contiguous RAM area equal to the required data storage size, 


(includes the parameter passing area, which is copied from the 
parent process” data area). The new process” registers are set 
up as shown in the diagram on the next page. The execution 
offset given in the module header is used to set the PC to the 
modules entry point. ` | | | : NC Lis 


(continued) 
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YSTEM.P 
- Service Request Descrip 


FORE (continued) 


When the shell processes a command line it passes a string in the 
parameter area which is a copy of the parameter part (if any) of. 
the command line. It also inserts an end-of-line character at 


the end of the parameter string to simplify string-oriented 


processing. The X register will point to the beginning of the 
parameter string. If the command line included the optional 


memory size specification (ën or 4nK), the snell will pass that 


size as the requested memory size when executing the FORK. 


If any of the above operations are unsuccessful, tne FORK is 
aborted and the caller is returned an error. | | | 


The diagram below shows how FORX sets up the data memory area and 


registers for a newly-created process. 


doe EE do uL A AA dr 

| NE 

| parameter ! 

! area ! 

i D 
4-----------------4 <-- X, SP 

| i 

t 4€ 

t A D 

l data area | 

i l | 

[| i 

t i 
$n nn ee nn t+ 
| direct page 

toe anne nnn nena nn + <-- U, DP 


= parameter area size ` 
PC = module entry point abs. address 
= F=¢, I-9, others undefined 


Y (tor of memory pointer) and U (bottom of memory pointer) will. 
always have a values at 256-tyte page boundaries. If the parent 
does not specify a parameter area, Y, X, and SP will be the same, 
and D will equal zero. The minimum overall data area size is one 


page (256 bytes). Shell will always pass at least an end of liae. 


character in the parameter area. 
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f a dU UR goën em ege: 
een wë gët EA 


INTERCEPT - | Set up e Signal intercept trap. F$ICPT 


ASSEMBLER CALL: 059 FSICPT 
MACHINE CODE:  — 102F Øg 


Address. of the intercept routine. » 
Address of the intercept routine local storage. 


HH 


INPUT: (I) 
(U) 


OUTPUT: None. 


a 


C bit set. 


ERROR OUTPUT: 
| | Appropriate error code. 


— CD 
— 
"oM 


This system call tells 0S-9 to set a signal intercept trap, where 
X contains the adddress of the Signal handler routine, and U 
contains the base address of the routine's storage area. After a. 
signal trap bas been set, whenever the process receives a Signal, 
its intercept routine will be executed. A signal will abort any 
process which has not used the F$ICPT service request to set a 
signal. trap, and its termination status (B register) will be the 


signal code. Many interactive progrems will set up an intercept . 


poutine to handle keyboard etort (control Di, and keyboard 
interrupt (control C). | 


The intercept routine is entered asynchronously because a signal 
may be sent at any time (it is like an interrupt) and is passed 
the following: | | sa 


U 


Address of intercept routine local storage. 
B E 


Signal code. 


NOTE: The value of DP may not be the same as it was when the 
FSICPT call was made. | | | | 


Whenever a signal is received, 0S-9 will pass the signal code and 
the base address of its data area (which was defined by a F$ICPT 
service request) to the |signal intercept routine. The vase 
address of the data area is selected by the user ard is typically . 
a pointer to the process” data area. E | 


The intercept routine is activated when a signal is received, 
then it takes some action based upon the value of tne signai code 
such as setting a flag in the process” data area. After the ` 
Signal has been processed, the handler routine should terminate . 

with an RTI instruction. a EC CES 
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ERROR OUTPUT: (CC) 
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GET ID. © Get process ID / user ID te TD 


ASSEMBLER CALL: 0S9 F$ID. 
MACHINE CODE: 193F ØC 


INPUT: Nothing. 


Process ID. 
User ID. — 


OUTPUT: (A) 
| (Y) 


C Bit set. | 
Appropriate errcr code. 


(3) . 


Returns the caller's process ID number, which is a byte value in 


the range of i tc 255, and the user ID which is à integer in the 
range 2 to 65535. The process ID is assigned by 0S-S and is 
unique to the process. The user ID is defined in the system 
password file, and is used by tne file security system and a few 
other functions. Several processes can have the same user 1D. . 
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LINE: Link to memory module. NS n FSLINK 


ASSEMBLER CALL: 059 F$LINK 
MACHINE CODE:  183F 00 


Address of the module name string. 
Module type / language byte. 


INPUT: 


"ow 


OUTPUT: Advanced past the module name. 
Module entry point absolute address. 
Module header absolute address. 
Module type / language. 


Module attributes / revision level. 


( 
( 
( 
( 
( 
( 
( 


"own 


m3 bd p» Cj rd 94 > pd 


(CC) 
(B) 


C bit set. 


ERROR OUTPU 
Appropritate error code. 


This system call causes 05-9 to search the module doe for a 
module having a name, language and type- as given in: the 
parameters. If found, the address of the modules. header is 
returned in U, and the absolute address of the modules execution 
entry point is returned in Y (as a convenience: this and other 
information Gan be obtained from the Puis header). The modules 
"link count is incremented whenever e LINK references its name, 
thus keeping track of how mary EE are using the module. 
If the module requested has ar attribute byte indicating it is 
not sharable (meaning it is not reentrant) only one process may 
link to it at a time. 


Possible errors: 
. (A) Module not found. 


(B) Module busy (not sharable and in use). 
(C) Incorrect or defective module header. 
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LOAD Load module(s) from a file. ` EL ESBOAD 


ASSEMELER CALL: OSS  F$LOAD 
MACEINE CODE: 12SF $21 ` 


INPUT: acess. of pathlist (file name ) 


Language / type (@ = any language / type) _ 


et et 
Hu 


OUTPUT: Advanced past pathlist | 

Primary moduie eniry point address 
Address of module header | 
Language / tyre 


Attritutes (éi revision level 


Deng Ser? Pdf Mars “ar 
HHH dH 


ERROR OUTPUT: (CC) = C Bit set 
.(8) = Appropriate error code 


Opens a file specified ty the pathlist, reads one or more memory 
modules “from the file into memory, then closes the file. All- 
modules loaded are added to the system module directory, and the 
first module read is LINKed. The parameters returned are the 
same as the LINK call and apply only to the first module loaded. 


In order to be loaded, the file must have the “execute 
permission and contain a module or modules that have a proper 
module header. The file will tbe loaded from the working 
execution directory unless the pathlist specifies otherwise. 


Possible errors: module directory full; memory full; plus errors 
that occur on OPEN, READ, CLOS= and LINK system calls. 
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“MEM Vi . Resize data memory area. oru | P$MEM 


ASSEMBLER CALL: 059 FÍMEN 
MACHINE COTE:  1£3F £7 
INPUT: (D) = Desired new memory area size in bytes. 


OUTPUT: (Y) = Address cf. new memory area upper pound. 
(D) = Actual new memory area Size in bytes. 


ERROR OUTPUT: (GE) 
(B) 


C Dit set. 
Appropriate error code. 


"uod 


Used to expand or contract the process/ data memory area. The new 
Size requested is rounded up to the next 256-byte page boundary. 
Additional memory is allocated contiguously upward (towards 
higher addresses), or deallocated downward from the old highest. 
address. If D= £, then the current a bound and size will be 
returned. 


This recuest can never return all of a process” memory, or the 
page in which its SP register. points to. ` Ee 


In Level One systems, the request may return an error upon an 
expansion request even though adequate free memory exists. This 

is because the data area is always made contiguous, and memory 
requests ty other processes may fragment free memory into 
smaller, scattered blocks that are not adjacent to the caller’s 
present data area. Level Two systems do not have this 
restriction because of the availability of hardware for memory 
| relocatior, and because each process has its own 'address Space . 
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FRERR Print error message. | oos S UESMEERR. 


ASSEMBLER CALL: OSS FSPERR 

MACHINE CODE: © 183F OF 

INPUT: (A) = Output rath number. 
(B) = Error code. 

OUTPUT: None. 


.C bit set. 


ERROR OUTPUT: (CC) 
- | (B) Appropriate error code. 


This is the system’s error reporting utility. It writes an error 


message to the output path specified. Most 05-9 systems will 
display: A i 


ERROR #<decimal number? 
by default. The error reporting routine is- vectored and can be 


replaced with a more elaborate reportirg module. To replace this 
routine use the dë service request. 
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PARSENAME 0 Parse a path name. Se Zenn 


ASSEMBLER CALL: OSS FSPNAM 


MACHINE CODE: 183F 10. 
INPUT: (X) = Address of the pathlist. 
OUTPUT: (X) = Updated past the optional EG 
oo (Y) = Address.of the last character of the name * 1. 
(B) = Length of the name. ; 
ERROR OUTPUT: (CC) = C bit set. - 
| . (8) = Appropriate error code. 
(X) = 


Updated past space characters. 


. Parses the input text string for a legal OS-9 name. The name is 
. terminated. by any character that is not a legal component 
character. This system call is useful for processing pathlist 
SC arguments passed to new processes. Also if X was at the end of a 
EC tathlist, a bad name error will be returned and X will be moved 
| | Pash any space characters so that the next pathlist in è command | ; 
ine may te persed. 


d 


Le that this system call EE one name, so several 
calls may be needed to process a pathlist that has more than one 
e. se ) 


“PORE FSPNAM CALL: 


E E AO GR ae ee Toa k4 


X 
LÍTISS TEE F$PNAM CALL: 
Am mr op om ET ee opt eof a fe fom fee oe ope e 


d Df g L/ 1 F'II!ILILE! ! TM eg 


ee ~ 


e 
e d e uu ET 
E A MR AO ARSS RS SE EE S í 


SEA le 
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SEMAP | Search tit map for a free area FSsBIt 


T m Cmm GIUM ee Vii 


ASSEMBLER CALL: 089  FSSBIT 


MACHINE CODE: i23F 12 


Beginning address of a bit map. 
Beginning bit number. 

Bit count (free bit block size). 
End of tit map address. 


" P 


zeginnirg bit number. 
Bit count. 


Ú H 


This system mode service request. searches the specified 


. allocation tit map starting at the beginning tit number for 4 


free block (cleared bits) of the required length. 


If po block of the specified size exists, it returns with tne 
carry set, beginning bit number end size of the largest block. 


are Systems Cor toration. 
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= SEND + Send a signal to another process. E face 


Seve, e gë: agua — 


ASSEMBLER CALL: | 0S9  FSSEND 

MACHINE CODE:  123F £8 

INPUT: (A) = Reciever’s d dde: ID number. | 
(8) = Signal code 

OUTPUT: None. 


C bit set. 
Appropriate error code. 


ERROR OUTPUT: | 


— CD 
— 
HH 


This system call sends a signal” to the process specified. The 
Signal code is a single byte Value 1.-.255. 


If the signal's destination process is sleeping or waiting, it 
will be activated so that it may process ine signal. The signal 
processing routine (intercert) will be executed if a signal trap 
was set up (see FSICPT), otherwise. the signal will abort the 
destination process, ard the Signal code becomes the ezit status 
(see WAIT). An exception is the WAKEUP signel, which activates a 
sleeping process but does. mot cause the signal ADUETOEDE routine 
to be executed. 


Some of the signal codes ge meanings defined by convention: | 


G = System Atort (cannot be. intercepted) 
1 = Wake Up Process pem "v 
2 = Keyboard Abort. 
3 = Keyboard Interrupt 

4-255 = user defined | 


If an EE is made to Send a signal to a process that has. an 
unprocessed, previous Signal pending, the current send request 
will be cancelled and en error will be returned. An attempt can 
be made to resend the signal later. It is good practice to issue 
a sleep call. for a few ticks before a retry to avoid wasting 
MPU time. ` 


For related information See ms FSICPT,  FS$wAIT, Abd FSSLEP 
service SE descriptions. . 
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INPUT: (I) 
OUTPUT: (X) 
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E p dine] 
d 


SLEEP Put calling process to sleep. FÉSLE? 


ASSEMBLER CALL: 059 FSSLEP 
MACHINE CODE: 103F @A 


Sleep time in ticks (8 = indefinitely) 


Decremented ty the number of ticks that the j 
process was asleep. 


H 


bit set 


ERROR OUTPUT: (cc) =C 
= Appropriate error code. 


(3) 


This call deactivates the calling process for a specified time, 
or indefinitely if X = 2. The process will be activated before. 
the full time interval if a signal is received, therefore 


sleeping E mba is a good way to wait for a signal without 
wasting CPU time 


The duration of a "tick" is system dependent but is e E ie 
1¢@ milliseconds. : 


Due to the fact that it is not known when the F$SLEP request was 
made àurring the current tick, FSSLEP can not be used for precise 
timing. A sleep of one tick is effectively a “give up Ee 
time slice’ request; the process is immediately inserted into the 
active process queue and will resume execution when it reaches. 
the front of the queue. A sleep of two or more ticks causes the 
process to be inserted into the active process queue after N-1 
ticks occur and will resume execution when it Ge the front 
of the queue. 
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dos get, T gët en: See 


SETPR Set process priority. e S n 


ASSEMBLER CALL: 0S9  FSSPRI 


MACEINE CODE: |  1£3F £D 


-INPUT: (A) 
(3) 


Process ID number. 
Priority: 

|. Ø = lowest 

255 = highest 


OUTPUT: None. 


C bit set. 


ERROR OUTPUT: (CC) 
Appropriate error code. 


(32) 


Changes the process’s priority to the new Value given. $FF is tne 
“highest  possitle priority, $00 is the lowest. A process car 
change another process” priority only if it has the same user IT. 
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SSC | Install function request _ | = PSSSYC 


ASSEMBLER CALL: 0S9 EF$SSTC 

ASSEMBLER CODE: — 103F 32 | » 
INPUT: (Y) = Address of service request initialization tatle. 
‘OUTPUT: None. | 


C bit set. 


ERROR OUTPUT: (CC) 
(B) Appropriate error code. 


D 
HH: 


This system mode service request is used to add a new function 
request to O0S-9's user and privileged system service request 


|» tables, or to replace an old. one. The Y register passes the 


address of a tatle which contains the function codes and offsets. 
to the corresponding service request handler routines. This. 
table has the following format: | | 


OFFSET 
ee $ | E d 
$99 ! Function Code |I <--= First entry. 
$01 t Offset From Byte 3! : 
$22 Pa Function Handler I 

ET ER Se cee RO <--- Second entry 
$04 | Offset Fro Byte € 1 
$25 x: To Function Eandler P 


<--- Third entry etc. 


 €--- End of table mark 


NOTE: If the sign bit of the function code is set, only the 
System table will be updated. Otherwise toth the system and user 

_ tables will be urdated. Privileged system service requests may 
be cal led oniy while SE a System Poutine, | | | 


- (continued) 
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SSVC (continued). 


The service request handler routine should process the service 
. request and return from subroutine witz an RTS instruction. They. 
may alter all MPU registers (except for SP). The U register will . 
pass the address. of the register stack to the service request 
chandler as shown in the following diagram: | 


| CFFSFT OSSDEFS 


-— NMEMONIC 
e o $ m 
Uer=> t: CC ` |. $o J| R$CC 
| Soo + | $1 R$D 
ft A ! |. $1 RSA 
Nb d 
! B ! $2 R&B 
Ët : 
! DP ! 2 $2 — R$DP 
drr af eee ame a ee eo 2 
! X ! $4 RSX 
he ee ae ee — — oe + 
! Y 4 $€ R$Y 
re eee | E 
! U |] $8 RSU ` 
afe ana anas ome, anum anoo cm ci dito ems up tito em + l 
! PC E $A © R$PC- 


o em» aum avo aum aes atro apr ene: Uu gem em gp em + 


Function request codes are broken into the two categories as- 
shown below: : 


$00 - $28 User mode service request codes. 


$29 - $34 Privileged system mode service request codes. 
When installing these service request, the 
Sign bit should be set if it is to be Rec. 
into the system table only. 


NOTE: These categories are defined by convention and not enforced 
by OSS. | | | 


Codes $25..$28, and $70..$7F will not te used by MICROWARE and 
are free for user definition. 
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SETSWI Set SWI vector. N | E FESS) 


ASSEMBLER CALL: 0S9 FSSSWI 
MACHINE CODE: 103F GE 


INPUT: (A) SWI type code. 


H H 


| |. (X) = Address of user SWI service routine. 
OUTPUT: None. | 
ERROR OUTPUT: (CC) = C dit set. 
| | (B) = Appropriate error code. 


Sets up the interrupt vectors for SWI,  SWI2 and SWI3 


instructions. Each process has its own local vectors. Each 
"SXTWSI call sets up one type cf vector accerdirg to the code 


number passed in A. 


WW 


1 = SWI o oe jl 
2 = SWIZ ut 
$ = SWI3 


When a process is created, all three vectors are initialized with 
the address cf the 0S-S service call processor. 


WARNING: Microware-suprlied software uses SWI2 to call 08-9. If 
you reset this vector these programs will not work. If you 


change all three vectors, you will nòt be able to call OS-9 at 
all. | 
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SETIME = . Set system date and time. = d FSSTIM 


ASSEMBLER CALL: OS  FéSTIM 
MACHINE CODE:  103F 16 


INPUT: (x) = Address of time packet (see below) 
OUTPUT: Time/date is set. 


C tit set. 


ERROR OUTPUT: , (CC) 
| Appropriate error code. 


(2) 


Hon 


This service request is used to set the current system date/time. 
The date and time are passed in a time packet as follows: 


ms dur dëm ERO ig AMD. VU CU 


minutes 
seconds 


. (€) 1988, 1981 Microware RS Corporation 
- PAGE 7S = 


(c) 1989, 


STEM PROGRAMMERS MANUAL 


1981 Microware ‘systems Corporation 


= PAGE 76 - 


0S-9 LEVEL ONE SY 
Service Request Lescriptions - User Mode. 
JN eco PIMES Get system date and time. STINE 

ASSEMBLER CALL: OS9 FSTIME 

MACHINE CODZ: 103F 15 
INPUT: (x) = Address of place to store the time packet. 

OUTPUT: Time packet (see below). | 
ERROR OUTPUT: (CC) =C bit set. 
(äi = Appropriate error code. 

"This returns bie current system date and time in the form of a 
six byte packet (in binary). The packet is copied to the address 
passed in X. The packet looks like: | | 

OFFSET VALUE 
TD a Ee 
` go t> year 
1  ! month 
2 l dar. 
3 ! hours 
4 Y minutes 
5 ! seconds. 


. 08-9 LEVEL ONE SYSTEM PROGRAMMER”S MANUAL. 
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Pv SUAM MIN gg mee ER 


UNLINE Unlink a module. 4 M4 SÉ sans 
ASSEMBLER CALL: 0S9  FSUNLE 
MACHINE CODE: 1837 22 


“INPUT: (U) = Address of the module header. ~ 
OUTPUT: Nothing. 


C tit set. 


ERROR OUTPUT: ` (CC) 
| Appropriate error code. 


(3) 


Tells 05-9 that the module is no longer needed by the calling 
process. The module's link count is decremented, and the module ` 
is destroyed and its memory deallocated when the link count 

equals. zero. The module will not te destroyed if in use by any 
other process(es) because its link count will be non-zero. In 
Level Two systems, the module is usually switched out of the | 
process” address space. S | 


Device driver modules in use or certain system modules cannot be 
unlinked.  ROMed modules can be unlinked but cannot be deleted 
from the module directory. i 
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Anus: ug ëmge O mg d 


WATT — © Wait for child to die. ee EK E 
ASSEMBLER CALL: 0S9  F$WAIT 
MACHINE CODE: ` 1903F 94 


INPUT: Nothing. 


OUTPUT: (A) = Deceased child's process ID. 
(is Child 's exit status code. 


ERROR OUTPUT: (CC) 
E (B). Appropriate error code. 


uou 


The calling process is deactivated until a child process 
terminates by executing an EXIT system call, or ty receiving a 
signal. The cnild/s ID number and exit status is returned to the 
parent. If the child died due to a signal, the exit status byte 
(B register) is the signal code. A dE | 


If the caller has several children, the caller is activated when 
the first one dies, so one WAIT system call is required to detect. 
termination of each child. | | | 


If a child died before the WAIT call, the caller is reactivated 
almost immediately. WAIT will return an error if the caller has. 
no children. | a 


See the EXIT description for more related information. 
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ASSEMBLER CALL: OS9 FSA64 ` 


INPUT: (X) 


OUTPUT: 


ERROR OUTPUT: (CC) 


-05-9 LEVE 
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 &64 — 7^ .Allocete a 64 byte memory block |». F$AE4 


RE 


MACEINE CODE: 1803F 20 


Base address of page table (zero if the page table 
has not yet teer allocated). | | 


H 


Block numter. 
Base address of rage table. 
Address of block. 


HHH 


(A) 
(X) 
(Y) 


= C bit set. 
(2) = Appropriate error code. 


This system mode service request is used to dynamically allocate 
.64 byte blocks of memory by splitting whole pages (256 byte) into 
four sections. The first 64 bytes of the base page are used as a 


page table”, which contains the MSB of all pages ir the memory. 


structure. Passing a value of zero in the X register will cause 


the FéAG4 service request to allocate a new base page and the 


first 64 byte memory block. Whenever a new page is needed, an. 
F$SRQM service request will automatically be executed. The. 


first byte of each block contains the block number; routines 
using this service request. Should not alter it. Below is a. 
diagram to show how 7 blocks might be allocated: M. | 


ANY 256 BYTE E ANY 256 BYTE 
MEMORY PAGE MEMORY PAGE 

BASE PAGE ---» ^ 4-----------—-—-* €. 4---—-----------4 
! l : IX t 
t PAGE TABLE ! I BLOCK 4 I 
t (64 bytes) ! ! (64 bytes) ! 
hae em + terre -—————-——— T 
DE v | H IX ` | 1 
! BLOCK 1 ! ) BLOCK 5 l 
! (64 tytes) ! 1 (64 bytes) N. 
A meer re a a me aeia ae EE 
A a A PT y 
! BLOCK 2 ! !  BLOCK6  ! 
1 (64 byte) ! ! (64 byte). l 
DE en a ane oF oa ee a oe er ee ama me er ee me + ` 
> | b IX mu 
! BLOCK 3 b | BLOCK 7 1 
1 (64 byte) |o E (64 byte) ! 


Block numbers range fror 1..N 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST ` 


(C) 1980, 1981 Microware Systems Corporation | 
NL - PAGE 79 - EE : 


0S-9 LEVEL CNE SYSTEM PROGRAMMER'S MANUAL 
Service Request Descriptions - System Mode 


AFRÜ Insert process in active process queue  FSAPRC. 
mI i i AAA 


| ASSEMBLER CALL: ^ OS9 FSAPRC 

MACHINE CODE: 103F 20. 

INPUT: (X) = Address of process descriptor. 
OUTPUT: None. | 


C bit set. — 
Appropriate error code. 


ERROR OUTPUT: 


— a 
td c3 
` See C 


This system mode service request inserts a process into the 
active process queue So that it may be. scheduled fer execution. 


All processes already in the active process Queue are aged, and 
the age of the specified process is set to its priority. If . the 
process is in system state, it is inserted after any other 
processes also in syster state, but before any process in user 
state. If the process is in user state, it is inserted accórding 

to its age | 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


- (C) 198%, 1981 Microvare Systems Corporation 
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INPUT? (X) 
SU nV) 


OS-O LEVEL ONE SYSTEM PROCRAMMER/S MANUAL 
Service Request Descriptions - System Mode ` 


.FIND-64 a E Find a 64 byte memory tlock M F$F64 


oo ote ` 


ASSEMELER: CALL: | 059. FSF64. 


MACHINE COLE: 103F <F 


Address of base page. 
Block number. 


now 


OUTPUT: (Y) Address of block. 
ERROR OUTPUT: (CC) = C bit set. 
(B) = Appropriate error code. 


This system mode service request will return the address of a 6é. 
byte memory block as described in the T$A64 service request. OS-9 
used this service request to find process Cescriptiors and path 
descriptors when given their number. GE 


Block numbers range from 1..N 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


(C) 1980, 1681 Microware Systems Corroration 
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IODEL ^ Delete 1/0 device from system ER ES TODE 
E | N het 

‘ASSEMBLER CALL: OS FSIODL 

MACHINE CODE:  103F 33 | 

INPUT: (X) = Address of an I/O module. (see description) 

OUTPUT: None. E | e 


C bit set. 


ERROR OUTPUT: 
i Appropriate error code. 


~ C3 
— 
H 


Wü o! 


This system mode service request is used to determine whether or 
not an 1/0 module is being used. The X register passes the 
address of a device descriptor module, device driver module, or 
file. manager module. The address is used to search the device 
table, and if found the use count is checked to see if it is 
zero. If it is not zero, an error conditicn is returned. 


This service request is used primarily by IOMAN and may be of 
limited or no use for other applications. fa : 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


(C) 1989, 1981 Microware Systems Corporation 
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IOQUEVE - Enter 1/0 queue = o (0. FSTOQU 


TTE 


ASSEMBLER CALL: 059  F$IOQU 
MACHINE CODE: 123F 23 
INPUT: (4) = Process Number. 
OUTPUT: None. 


C bit set. 


ERROR OUTPUT: (cC) 
(B) Appropriate error code. 


"n H 


This system mode service request links the calling process into 
the 1/0 queue of the specified process and performs an .un-timed 
Sleep. It is assumed that routines associated with the specified 

process will send a wakeup signal to the calling process. : a af 


NOTE: TEIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


(C) 1980, 1981 Microware Systems Corporation 
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Sg 


^ 
"em 


ERROR OUTPUT: 


08-9 LEVEL ONE SY 
st I 


"EM PROGRAMMER “S MANUAL 
Service Request C ion 


AMMER'S 
s - System Mode 


 SETIRC | de Add or remove device from IRQ table. ~ FSIRC 


o pett ` 


ASSEMBLER CALL: 089 FS$IRO 
MACHINE CODE: 1803F 2A 


INPUT: (X) = Zero to remove device from table, or the address 
KR of a packet as defined below to add a device to 
the IRQ polling tatle: laa | 


[x] = flip byte 
2[X*1] = mask byte 
[X42] = priority 


= Address of service routine’s static storage area. 
(Y) = Device IRQ service routine address. 
= Address of the device status register. 


OUTPUT: None. 


C) = C bit set. 
) = Appropriate error code. 


"nis service request is used to adda device to or remove a 


device from the IRQ polling tatle. To remove a device from the 


table the input should be (X)=2, (U)= Addr of service routines 
static storage. This service request is primarily used by device 
driver routines. See the text of this manual for a complete 


discussion of the interrupt polling system. 


PACKET DEFINITIONS: 


Flip Byte This byte selects whether the bits in the device 
. status register are active when set or active 
when ake A set bit(s) identifies the active 

bit(s). 


Mask Byte | This byte selects one or more bits within the 
device status register that are irterrupt request 
fleg(s). A set tit identifies an active tit(s).. 


Priority || The device priority number: 
2 = lowest 
255 - highest 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


. (C) 1980, 1981 Microware Systems Corporation 
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Service Request Lescriptiors ~- System Mode 


ONITPRCS.. eesse | Start. next process .- mS —— i EH e o FŠNPRC ` 
: . A REM 


ASSEMBLER CALL: OSS FSNPRC 
MACHINE CODE: 103F 2D 
INPUTS None. 


OUTPUT: Control does not return to caller. 


This system mode service request takes the next process out of 
the Active Process Queue and initiaites its execution. If there : 
is no process in the queue, 05-9 waits for an interrupt, and then 
checks the active process queue again. 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


(C) 1980, 1981 Microware Systems Cerperation 
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C 


C) 


O 


INPUT: (X) 
(A) 


ERROR OUTPUT: (CC) 
| (8) 


05-9 LEVEL ONE SYSTEM PROGRAMMER S MANUAL 
Se ce Requ d 


ervice q est Descriptions - System Mode 


R64 | Deallocate a 64 byte memory block |. . F$R6E4 
| i E de g | | oA 


ASSEMBLER CALL: 059  FSR64 
MACHINE CODE: 103F 31 


= Address of the base page. 
= Block number. 


CUTPUT: None. 


C bit Seck | ; 
Appropriate error code. 


uM 


This system mode service request deallocates a 64 byte block of 


memory as described in the FSA6# service request. 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST 


(C) 1982, 1981 Microwere Systems Corporation 
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Service hequest Descrirtiors ~ System Mode 


SRQMEM | System memcry request 


ASSEMBLER CALL: 0S9 F%SRQM 
MACHINE CODE: 1037 28. 
INPUT: (D) 


Byte count. 


OUTPUT: (U) = Beginning address of memory area. 


ERROR OUTPUT: (CC) =-C bit set. 
D (B) = Appropriate error code. 


< This system mode service request allccates a block of memory 
the top of available RAM of the specified size. GER 


requested is rounded to the next 256 byte vage boundary. 


NOTE: TEIS IS A PRIVILEGED SYSTEM MODE SERVICE RECUEST 


(c) 1982, 1981 Microware Systems Ceruan tio 
Sg oe PAGE BS 


F$SRQM 
Ee 


Leg, dem ee 


from 
size. 


0S-9 LEVEL ONE SYSTEM PROGRAMMER’S MANUAL ` 
Service Request Descriptions - System Mode 


“SRIMEM c | Return System Memory = o Pt | = FSSRTM 


-ASSEMBLER CALL: OSS F$SRTM 
MACHINE CODE: 103F 29. 


U) Beginning address of memory to return. 


INPUT: (U) = 
(D) = Number of bytes to return. 


D 
e: 


OUTPUT: None. 


C bit set. 
Appropriate error code. 


ERROR OUTPUT: (CC) 
(EI 


This Ó mode service request is used to deallocate a block of 
contiguous 256 byte pages. The U register must roint to an even 
. page boundary. 


NOTE: THIS IS A PRIVILEGED SYSTEM MODE ee REQUEST 


B 


` (C) 19890, 1981 Microware Systems Corporation 
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KEE E 


ERROR OUTPUT: (CC) 


-05-9 LEVEL ONE SYSTEM PROGRAMMER ’S MANUAL — 
Service request Descriptions - System Mode 


VOD © Verify module — EA OE BOIMED. 


vd ERA e 


a pt at i 


ETE e 


ASSEMBLER CALL: 059  F$VMOD. 


MACEINE CODE: 103F 2E 


INPUT: (X) = Address of module to verify. 


OUTPUT: (U) = Address of module directory entry. 


C pit set. 
Appropriate error code. 


(3) 


"fhis system mode service request checks the moule header parity 
and CRC bytes of an OS-9 module. If these values are valid, then 
the module directory is searched for a module with the same name. 


1f a module with the Same name exists, the ore with the highest 


revision level is retained in the, module directory. Ties are 
broken in favcr of the established module. 


NOTES. THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST. 


(C) 1988, 1981 Microware Systems Corporation : 
| cue NOE o PAGE 89 - i $ 3 


does NOT "reserve the device in question - it just prepares i 


90S-2 LEVEL ONS SYSTEM PROGRAMMER “S MANUAL 
Service Request Descriptions. - 1/9 Requests 


wen. ip cies AME. me ma 


ATTACH © Attach s new device to the system. ` I$ATCH 
ASSEMBLER CALL: | CS9  ISATCH 
MACHINE CODE:  1%3F 80 


Address of device name string. 


INPUT: (X) 
(A) = Access mode. 


ton 


OUTPUT: mi Address of device table entry. 
C bit set. 


ERROR OUTPUT: | 
| Appropriate error code. 


(CC) 
(3) 


This service request is used to attach a new device to the 

system, or verify that it is already attached. The device's rame 
string is used to search the system module directory to See if a 
device descriptor module with the same name is in memery (this. 
is the name the device will ve known by). The descriptor module 
will contain the name of the device’s file manager, device driver 
and other related information. If it is found and the device is 
not already attached, 05-9 will link te its file manager and 
device driver, and then place their address’ in a new device 
table entry. Any permanent storage needed by the device driver 
is allocated, end the driver's initialization routine is called 
(which usually initializes the hardware). | 


If the device has already been attached, it will not be 
reinitialized. EE j 


An ATTACH system,call is not required to perform routine 1/0. I 


ct ct 


for subsequent use by ary process. Most devices are automatically 
installed, so it is used mostly when devices are dynamically 
installed or to verify the existance of a device. MAE 


The access mode parameter specifies which subsequent read and/or 


write operations will be permitted as follows: 


Use device capabilities. 
Read only. 
Write only. 

Both read ard write. 


p Uu H 


ANH & 


ware Systems Cerpcratioa 
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wues As gier dës ga dite 


ee gës Ue pg of epe ` 


CEDIR | Change working directory. ` CI$00IE 


ASSEMBLER CALL: 0S9 I$CDIR 
MACHINE CODE: 123F 86 


Address of the pathlist. 
Access mode. 


HH 


INPUT: (X) 
(A) 


OUTPUT: None. B 
C bit set. | 
Appropriate error code. 


H H 


ERROR OUTPUT: (CC) 
(ei 


Changes a process” working directory to another directory file 


specified ty the pathlist. | The file must be a directory, and 


have read permission (public read if not owned by the calling 
process). New files may be added to the directory only if it has 
similar write permit attributes. 


ACCESS MODES: 


Read 

Write 

Update (read or write) 
Execute 


n wm 


DODE 


If the access mode is read, write, or update the current data 


directory is changed. If the access mode is execute, the current 


execution directory is changed. 


(ei 1988, 1981 Microware Systems Corporation 
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CLOSE a Close a path to a file/device. t. Ñ | *1$CLCS 


ASSEMBLER CALL: OSS  I$CLOS 


MACHINE CODE: = 1@3F BF 


INPUT: (A) = Path number. 
OUTPUT: None. 


C bit set. 


ERROR OUTPUT: ( 
( Appropriate error code. 


— C3 
w 
HH 


Terminates the 1/0 path specified by the path number. 1/0 can no 


longer be performed to the file/device, unless another JPEN or 


 CREATF call is used. Devices that are non-sharabie become 


available to other Tequesting processes. All OS-S internally 
managed buffers and descriptors are deallocated. | 


Note: Because the 059 FSEXIT service request automatically closes. 
all open paths (except the standard I/O paths), it may not de 
necessary to close ther individually with the 059 I$CLOS service 


request. 


Standard  I/O paths are not typically closed except when it is 
desired to change the files/devices they correspond to. — 


(C) 1980, 1981 Microware systems Corporation 
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CREATE | - Create e path to a new file. | ICREA 


ASSEMBLER CALL: OSS ISCREA 
“MACHINE CODE: | i1083F 83 — 


INPUT: (X) = Adéress of the pethlist. 
Access mode. 


File attributes. 


m 
ef 
"on ou 


Updated pest the petnlist (trailing blanzs skipped) 
Path number. o 


OUTPUT: (X) 
(4) 


C bit set. s 
Appropriate error code. 


ERROR OUTPUT: (CC) 
(3) 


Used to create a new file on a multifile mass storage device. The 
pathlist is parsed, and the new file name is entered in the 
specified (or default working) directory. The fiie is given the. 
attributes passed in the B register, which has individuel tits 

defined as follows: Ee A Y E | E cd 


bit @ = read permit 

bit 1 = write permit 

bit 2 = execute permit ` 

bit 3 = public read permit 
bit 4 = public write permit 
pit 5 = public execute permit 
bit 6 = sharable file 


‘The access mode paremeter passed in register A must be either 
WRITE or UPDATE". This only affects the file until it is 


closed; it can be reopened later in any access mode allowed ty | 


, 


the file attributes (see OPEN). Files open for "WRITE may &llcw 
faster data transfer then "UPDATE , which sometimes reeds to pre- 
read sectors. These access codes are defined as given below: 


2 
3 


Write only. 
Update (read and write). 


"on 


NOTE: If the execute bit (bit 2) is set, tne file will be created 
in the working execution directory insteed of tne working date 
directory. : E ILE e 


(continued) 
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CREATE (continued) 


The path number returned by 0S-9 is used to indentify the file in 
subsequent 1/0 service requests until the file is closed. 


The file’s owner is the user who created it. Other. users may 
access the file only if the appropriate permission tit(s) are set 
Jin the file attributes byte. ioe . 


No data storage is initially allocated; this is dore 


automatically by WRITE end FUTSTAT calls. 


An error will occur if the file name already exists in the 


directory. CREATE calls that specify non-multiple file devices 


(such as printers, terminals, etc.) work correctly: the CREATE 


 behaves the same as OPEN. Create cannot be used to make directory 


files (see MAZDIR). 


(C) 1980, 1981 Microware Systems Corporation 
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ERROR OUTPUT: (CC) 
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DELETE Delete a file.” En eee LEER 


wë dim dime gie diem od 


ASSEMBLER CALL: 0SO I$DLET 
MACHINE CODE: 163F 87  — 


INPUT: (X) - Address of pathlist. 
OUTPUT: (X) = Updated past pathlist ele spaces skipped): 


C tit set. 
Appropriate errcr code. 


"ow 


(5) 


This service request deletes the file specified ty the pathlist. 
The file must have write permission attributes (public write if 
not the owner), and reside on a multifile mass storage device. 


EE to delete devices will result in an error. 


(C) 1980, 1981 Microware Systems Corporation s 
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CT 


ERROR OUTPUT: | (CC) 
0). 


0S-9 Li 
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uest Descriptions - 1/0 Requests 


ms mire ae ath A ae 
en wm Je ae du "ës 


DETACH —— | Remove a device from the system. - . IS$DTCR- 


ASSEMBLER CALL: 0S9 I$DTCH 
MACHINE CODE: ` 123F 81 


INPUT: (U) = Address of the device table entry. ` 


OUTPUT: None. - 


C bit set. | 
Appropriate error code. 


"ou 


‘Removes a device from the system device table if not in use by 


any other process. The device driver's termination routine is 


called, then any permanent storage assigned to the driver is 


deallocated. The device driver and file manager modules 
associated with the device are unlinked (and maj be destroyed if 
not in use by another process. | | | 


The I$DTCE service request must be used to un-attach devices that 
were attached with the I$ATCE service request. Both of these are 
used mainly by IOMAN and are of limited (cor no use) tc the user. 


SCFMAN also uses ATTACH/DETACH to setup its second (echo) device. 


(C) 1982, 1981 Microware Systems Corporation W 
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DUP Duplicate UN K E 


* pe RE Rd 
mmer. duas mër SET mmm 


ASSEMBLER CALL: 059 I$DUP 


“MACHINE CODE: 1083F 82. 


ar TEE 


ERROR OUTPUT: (CC) 


INPUT: (A) = Path number of path to duplicate. 


OUTPUT: (B) = New EES number. 


= C bit set. ) 
(8) = Appropriate error code. 


Given the number of an existing path, returns another synonymous 
path number for the sare file or device. SHELL uses this. 
Service request when it redirects I/O. Service requests using 


either the old or new patn numbers DERS on the same file or 
device. 


NOTE: This only increments the "use count of a path descriptor 


and returns the Synonymous path number. The path descriptor is 


not copied. 


(C) 1980, 1981 Microware Systems Corporation 
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‘SE 


GETSTAT ` 


ERROR OUTPUT: (CC) 
de (3) 
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¿176511 


E —-—P—32J—P--— 


Ee status. 


ASSEMBLER CALL: OS9 I$GSTT. 


MACHINE CODE: 1Ø3F 8D 


INPUT: H = Path number. 


= Stetus code. 
(Other registers depend upon status code). 


OUTPUT: (depends upon status code) 


C bit set. 
Appropriate errcr code. 


This system call is a "wild card" call used to handle individual 


device parameters that: 


a) are not uniform on all devices 
b) are highly hardware dependent 
cl need to be user-chengable 


The exact operation cf this call depends on the device: driver 
and file manager associated with the path. A typical use is to 
determine a terminal’s  paramaters for  tackspace SEE ae 
delete character, echo on/off, null padding, paging, etc It- is 
commonly used in conjunction with tne SETSTAT service request 
which is used to set the device operating parameters. Below are 
the presently defined function codes fer GETS TAT: 


se 


oor RED EP AO APA SS wm a GEE epp. SANT: EED d Ga op ie WER A EE om um GEED GUI vm em emt gt gr et MEER AQUD WERE “EP GER a er (UND. eee a ven m 


NMEMONIC CODE 


wë UND ar EP ae UID eee “EER. wem era qum 


SS.0PT . 8 Read the 32 byte option section of the 
| path descriptor. e 
SS.RDY 1 Test for data ready on SCFMAN-type device. 
SS4SI1Z 2 Return current file size (on REFMAN- type 
devices). 
SS.POS mou Get current file position. 
SS .20F 6 Test for end of file. 
(continued) 
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. CODE | | 

7-127 Reserved for future use. 

CODE ` j | | | | | 
128-255 — Tnese getstat codes and their parameter passing. 


conventions are user definable (see the sections of 
this manuel on writing device drivers). The function 
code and register stack are passed tc the device 


 Parareter Passing Conventions 
The parameter passing conventions for each of these function 
codes are given below: | | | o | 


We e LD E ee See amer pm em Se gi ge gr wm "ër EE me SE me Zar ge e SE Se ME e — DT ee gn vir Wer Me gë Man pm E er D me MEE ET Ge erer E ME 


SS.0PT (code 2): Read option section of the path descriptor. 
Path number 


Function code £ 


INPUT: (A) 
(B) = | a | 
Address of place to put a 32 byte status packet. 


(X) 
OUTPUT: Status packet 


O pit set. 
Appropriate error code. 


ERROR OUTPUT: (CC) 
(B) 


This getstat functicn reads the option section of the péth 
descriptor and copies it into the 32 byte area pointed to by the 
X register. It is typically used to determine the current 
settings for echo, auto line feed, etc. For a complete 
description or the status packet, please see the section of this 
manual on path descriptors. | | | 


pp eo erede oed eei E E E E E EE E SEE WE ME MED EE MEE Cu au duh MEM quA ^ia AMET UMS A Mene Mb AR mene Uu a abun EE EE EE EE AE EE EE EE 
Quem cum bes URP deum sub uum emt: gr ANN DU. Give Fe uio Gne gë d dë nw mem dë "E iam Er oe Mr e MP EO DE TA LELIE DI MI ee gn MR e mm me ee MEE ger gë me e STE pe "e me ms ër Ee E ME "er 
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GETSTAT (continued) 


seer rors sets sss SSS SSS nran es E EE E cers eS SSS SSS SSS SSS 


SS.RDY (code 1): Test for data available on SCFMAN supported 


devices. | 
INPUT: (A) = Path number. | 
(B) = Function code 1 
OUTPUT: © -—————————————————— MÀ 
"| Ready ! Not Ready ! Error 1 
DUE p———— Eeer be ee ee ee es 
(CO) 1 C bit clear ! C bit set t C bit set ! 
. sper am an ee ee am aren ae dm me —— en emer ee ee sje Sn dim i oon we ee cas nee ap -Ae 
(B) zero 1 $FE (ESNRDY) ! ERROR Code ! 
dm me me oue € M MÀ he et mam Se oe Ee toe Së + 


x WA = SS De Se 


e A —— ee "Em ge Tt oe "ET e ge A—— ME DE e da DEE MERE Gam emm emm aue Sede eum AE WEE We SE WERE EE aue MEE NE Gies cms ME ME am DE DER 


/SS.SIZ (code 2): Get current file size (RBFMAN supported 


devices only) 
INPUT: (A) = Path number. 
(B) = Function code 2 
OUTPUT: (X) M.S. 16 bits of current file size. ` 
| (U) = L.S. 16 bits of current file size. 
ERROR OUTPUT: (CC) = C bit set. 
(B) = Appropriate error code. 


EE EE MERE SEEP EE EE EE EE AAA pp eei eia o P E E E E E 
A HE HE E E DE DE A E EE e Gem mm o WE HE e EE E E e ME ye DE EE ee ED DR E DE E we e e ee zg am ge mm ise due cm nom zë mem 


© SS.POS (code 5): Get current file position (RBFMAN supported ` 


devices only). 


INPUT: (A) = Path number 
| (3) = Function cede 5 
OUTPUT: (x) = M.S. 16 bits of current file pesition. 
) = L.S. 


16 bits of current file position. 


C bit set. 


ERROR OUTPUT: - | j 
= Appropriate error code. 


chin aan au OND wa mi am MEE E E —— MEE aa RE OE. aa ae e me EE deo pere e wtih mint DE HET EE E DR ME EE DE DE ET EL DE Soe pp O seis, san A enn ineo o O dode “OY 
RD DU DE IE De De “eg Me ZR VD wa. mee mp Ws use E uma ED er camem cun E TE Me Mn WE WE DE DE DR ET ME A vag ze e ren D ae WER E WER MEE ME MA EE Mn Mar rr Er ME EP ME EE 
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GETSTAT (continued) . 


A er ee ee ee er Da ee ME me DER ee er WE MET mee me ME ee E Tee re cae Se em LG em ames eme mme dms ib mm qun pem gë 


os. EOF (code 6): Test for end of file. 


Path number. 


INPUT: (A) 
(B) Function code 6 


. OUTPUT: Aere see ee ee Se EE EE EE EE SE EE EE E E EE EE SS A+ ' 


! Not- EOF ! EO} ! FRROR ! 
HESPERIA SSS SSS + 
(CO) ! C bit Clear ! C bit set !. C bit set ! 
————— ——Ó—Ó drr EE we $e mnt 
(B) ! Zero 1 $D3 (ESEOF) ! Error Code ! 
dar sm ma ee ar a oe a a AA A o GE dr SEE + 


mr OE DT EE ER EE DE TT De Me me Dr DE ME Mr ME E E ME ME DE ME sm EE STEELE mn je was ar dae dae sme Gee eme de E EE eue cm mm 
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ERROR OUTPUT: (CC) 
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MAXDIR » Make a new directory. SR | | ^ TSMDIR 
ASSEMBLER CALL: 059  I$MDIR 
MACHINE CODE: 103F 85 ` 


Address of pathlist. 


INPUT: (X) = 
(B) = Directory attributes. 


OUTPUT: (X) Updated.past pathlist (trailing spaces skipped). 


C bit set. 
Appropriate error code. 


(B) os 


MAEDIR is the only way a new directory file can be created. It 
will create and initialize a new directory as Specified by the 
pathlist. The new directory file contains no entries, excert for 


an entry for itself ('.') and its parent directory ( .. 


The caller is made the owner of the directory. MAKDIR, does not 
return a path number because directory files are not opened ty 
this request (use OPEN to do. so), The new directory will 


automatically have its "directory bit Set in tne access 
permission attributes. The remaining attributes are specified by 
the byte passed in the B register, which has individual bits 
defined as follows: I2 | e 


tit @ = read permit 

bit 1 = write permit 

bit 2 = execute permit 

bit 3 = public read permit 
bit 4 = public write permit 

bit 5 = public execute permit 

bit 6 = sharable directory 
bit 7 = 


(don’t care) 
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OPEN — - Open a path to a file er device. ISOPEN ` 
ASSEMBLER CALL: 0S9 ISOPEN 
MACHINE CODE: 163F 84 


Address of pathlist. 


INPUT: (X) 
| Access mode (D $ PE PW PX E W R) 


(A) 
OUTPUT: (X) 
(A) 


Updated past pathlist (trailing spaces skipped). 
Path number. 


H 


C bit set. 
‘Appropriate error code: 


ERROR OUTPUT: (CC) 
(3) 


Opens a path to an existing file or device as Specified by the 
pathlist. ` A path number is returned which is used in subsequent. 
service requests to identify the file. 


The access mode parameter Specifies which Geen read and/or 
write operations are permitted as follows: | 


i= read mode 
2 = write mode | 
3 = update mode (both read and write) 


Update mode can be slightly slower because sector pre-reads may 
te required for random access of bytes. The access mode must 
conform to the access permision attributes associated with the 
file or device (see CREATE). Only the owner may access a file 
unless the EE ‘public permit. bits are set. 


Files can be opened ty several processes (users) EE 
Devices have an attribute that E whether or rot they are 
Sharable on an individual basis. 


NOTES: If the execution bit is set in the access A 0S-9 will 
begin searching for the file in the workirg execution 
directory (unless the pathlist begins with a slash). 


The sharable bit (bit 6) in the access mode can nót lock | 
other users out of a file in 0S-S Level I. It is present. 
only for upwerd compatatility SE 08-9 Level. Il, E 


Directory files may be reed or writes if the D bit. (bit 
7) is set in the acces mode. | 
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READ ` | Bead data from a file or device. |. I$READ 


ASSEMBLER CALL: | 0S9  ISREAD 
MACEINE CODE: 183F 89 
Address tc store data. 


Number of bytes to read. 
Path number. | 


HHH 


(A) 


H 


Number of bytes actually read. 


C bit set. | 
Appropriate error code. 


ERROR OUTPUT: c 


Reads a specified number of bytes from the path number given. 


The path must previously have been opened in READ or UPDATE mode. 
The data is returned exactly as read from the file/device without 
additional processing or editing such as backspace, line delete, 


 end-of-file, etc. 


AFTER all data ina file has been read, the next ISREAD service 
request will return and end of file error. 2 


NOTES: The keybcard abort, keyboard interrupt, and  end-of-file 
characters may be filtered out of the input date on 
SCFMAN-type devices unless the corresponding entries in 
the path descriptor have been Set to Zero. It may be 
desirable to modify the device descriptor so that these 
values in the path descriptor are initialized to zero when 
the path is opened. os b 


The number of bytes requested will be read urless: 
A. An end-of-file occurs MN 


B. An end-of-record occurs (SCFMAN only) 
C. An error condition occurs. 


C) 1980, 1981 Microware Systems Corporation 
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READIN |. Read a text line with editing. 7 EL 


ASSEMBLER CALL: ` 0S9 ISRDLN 
MACEINE CODE: 123F 83 


INPUT: (X) = Address to store data. 
(Y) = Maximum number of bytes to read. 
(A) = Path number. 

OUTPUT: (Y) = Actual number of bytes read. 


C bit set. 


 . ERROR OUTPUT: (CC) 
| ) Appropriate error code. 


(3 


"t 


This system call is the same as “READ” except it reads data from 
the input file or device until a cerriage return character is 
encountered or until the maximum byte count specified is reached. 


line editing will occur on SCFMAN—tfpe devices. Line editing 
refers to backepach, line delete, echo, automatic line feed, etc. 


 SCFMAN requires that the last. byte: entered be an end-of-record. 
Character (normally carriage return). If more data is entered 
that the maximum specified, it will not be accepted and a  PD.OVF . 

character (normally bell) will be echoed. l | 


After all data in a file has been read, the next I$RDLN service 
request will return an erd of file error. 


NOTE: For more information on line editing, see the section of 


e this pe on 'SCFMAN line editing features . 
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— INPUT: 


ERROR OUTPUT: 
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SEEK ` Reposition the logical file pointer. LM I$$ERK 


mp wn <a. che "pt 


ASSEMBLER CALL: 0S9  ISSEEK 
MACHINE CODE: . 183F 88 


th number. | | | 
S. 16 bits of desired file position. 
S. 


(A) = P 
(xX) = M : 
(U) = L.S. 16 bits of desired file position. 


OUTPUT: None. 


C bit set. 
Appropriate error code. 


w CD 
— 
uu 


This system call repcsitions the "file pointer ; the 32-bit 
.address of the the next byte in the Kcd RI read from or 
written to. 


A seek may be performed tc any value even if the file is not 


large enough. Subsequent WRITEs will automatic ally expand the ` 
file to the required size (if possible), but READS will return an ` 
end-of-file condition. Note that a SEEX tc address zero is the 

Same as a rewind operation. l | 


Seeks to non-random access devices are Kate ignored and return 
| i dc error. | 
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ere e an ime aM mete 


`" "SETSTAT _ Set file/device status. — | tiU DSTI 


ASSEMBLER CALL: 0S9 ISSSTT 
MACEINE CODE: 103F BE 


INPUT: (A) = Path number. 
— (B) = Function code. 
(Other registers depend upon the function gäer, 


- OUTPUT: (Depends upon the function code). 


ERROR OUTPUT: (CC) 2.C bit set. | 
| (B) = Appropriate error code. 


This system call is a "wild card” call used to handle individual 
device parameters that: | | 


a) are not uniform on all devices 
b) are highly hardware dependant 
c) need to be user-chagable 


The exact operation of this call depends on the device driver and 
file manager associated with the path. A typical use is to set e 
terminal's parameters for backspace character, delete character, 
echo on/off, null padding, paging etc. It is commonly used in 


conjuction with the GETSTAT service See which is used to read ` 


the device”s operating parameters etc Below are the presently 
. defined function codes: | 


NMEMONIC CODE FUNCTION 


CU ate n> gum de geen em eg AMD dm geen one RTT E E dum qe um en Sane Sa te SS N ins ci e i qu m ane demm aee. 


SS.0PT $e ` Write the 32 byte dices section of the 
| | | rath gescriptor to set the device 
SS.SIZ $2 | Set the file size (for RBFMAN type 
| devices only). 
SS.RST SS ` Restore head to track zero. 
SS.WRT $4 Write track. 


- (C) 1982, 1981 bono Va. Systems. Corporation 
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CODES | | ae | $* | | | : [T E 
128-255 These SETSTAT codes and their parameter passing 


INPUT: (A) 
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SETSTAT (continued) 


CODES | | : | 
5-127 Reserved for future use. 


conventions are user definatle (see the sections of 


this manual on writing device drivers). The function ` 


code and register stack are passed to tne device 
driver. ; 


* 
Ld 


Parameter Passing Conventions 


“The parameter passing conventions for each of these function 
codes is given below: 


mum anum. das Are Re HIED ME VEND MAR Mi. TE "HU. ites dune aer any Rae can «Mum Rus quat Mm MM. WEE Mp M MP EE suey GS Va Say WEE DE S GS TUNE eo mem Gus cru aids WEM TREE GE WENN dem uae dep) aes HT ADU, chers UB A EE EE E E 


SS .OPT (code 0): Write cption section cf path descriptor. 


Path number 
Function code 2 : 


(B) WET. 
Address of a 32 byte status packet 


(X) 
OUTPUT: None. 


ERROR OUTPUT: (CC) C bit set l | 
(35) Appropriate error code. 


This setstat function writes the option section of the path 
descriptor from the 32 byte status packet pointed to by the X 
register. It is typically used to set the device operating 
parameters, such as echo, auto line feed, etc. For a complete 
description of what is in the status paczet, please see the 


section of this manual on path descriptors. 


oe ma nae cone op MR MEE EE ED Er SS mamas den arie. GE Sinan OE) EE. A O MEE ME EER EE MA ale GEE. wan EER Siam GEE AE EE EE HE ME WE DE DE DE DE WE DE ER See mes DE LE LE TE RE TE ETE DE 
2 22I ee ee cee rn A EA OO zë af më, mm gem e RUG SEED SEN Sa ee "EC EOD n cin gë er e wg WP ep ap MM ae quem cum Pe ee ëm dn Em UA vm ër E WEE et ADM pe 
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 SETSTAT (continued) 


—SS.SIZ (code 2): Set file size (R3FMAN-type devices) 


Path number 

Function code 2 

M.S. 16 bits of desired file size. 
L.S. 16 bits of desired file size. 


INPUT: (A) 


(X) 
AR 


-QUTPUT: None. 


u om wo 


C tit set. 


ERROR OUTPUT: (CC). 
(3) Appropriate error code. 


This setstat function is used to set the file size  (REFMAN 
supported devices only). | 


e wen ee, wn wë EER vn ET më pe dar WEE EE WEE WEES EE. GS of e vm dp me e edi mpl E ER cine E PI ME ME DE DE EE TE EE LE p————PMráÀ— € —— geg, ter ot unre wm ge o ee eme par: Ze gem pene 


SS.RST (code 3): Restore head to track zero. 


Path number 
Function code ¢ 


INPUT: (A) 
n (E) 


OUTPUT: None 


C bit set $ 


ERROR OUTPUT: (CC) - 
| (B) = Appropriate error code 


we UE A wë MEE. GEE MEDE Pe O CI ag ge, eie perenne DÀ e we CET ge E wee E e Mi, HE, E Ge E HE E E GE amm yews Wem quM (UD COMO we ae, Sire AER e MAU KE. up ID MEMO gg ee Apu ARO PS me Gëf GER me ds e 
We E E ee E E E See E Se. ge ge eme ee, zem A ve "gn ee dr gem Se gi ein ëm ëm gë ge Ze Some ër de om ee mm ed QE que dee E Same — MENS Se gem wee ege mn diis o emm Mus ge SEN MUT gem dim zë dice gë ge Mw 


SS.WTK (code 4): Write track. | 


INPUT: Path number 


(A) = 
(B) = Function code 4 
(X) = Address of track buffer. 
(U) = Track number (L.S. 8 tits) 
(Y) = Side/density | 
Bit BG = SIDE (Ø = side zero, 1 = side one) 
Bit Bl = DENSITY (Ø = single, 1 = ouble) 
 QUTPUT: None | 
ERROR OUTPUT: (CO) = C bit set 
(8B) = Appropriate error code 


mn vm oa e me o er vi A ve o IE. A AC OS —— GEE om mm E gp HEER e DER E GEE WET MEER E EE E E EE ME EE ME tenn ME BU DE E E MI Ebr e E 
PE AAI "MOD Ve du ep "rer dt emer oeren ed j[-— emm dii gege, UD gr, e um gp: a up SERA Ghee AL WKN. ër eer iR Weg "rz gz A. mp ton nr "naim fm ép af "em o ër der gar de ERR pre Di geg gg mr mem mz 
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WRITE © Write deta to a flle or device. e ISWRIT 


ae nen, sare en ETE. de 


ASSEMBLER CALL: ` 0S9 I$WRIT 


MACHINE CODE: 103F BA 


Address of data to write. 
Number of bytes to write. 
Path number. ME | 


INPUT: (X) 
d (Y) 
(A) 

OUTPUT: (Y) 


woud 


Number of bytes actually written. 


H 


C bit set. 
Appropriate error code. 


ERROR OUTPUT: (CC) 
(B) 


HH 


WRITE outputs one or more bytes to a file or device associated 


with the path number specified. The path must have been OPENed 
or CREATEed in the WRITE or UPDATE access modes. 


Data is written to the file or device without processing or 
editing. If data is written past tne present end-of-file, the 
file is automatically expanded. SS B e EE | 
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WRITELN Write a line of text with editing. 27 ISWRLN 


ASSEMBLER CALL: 059 I$WRLN 

MACHINE CODE: 103F 8C 

INPUT: . (X) = Address of data vor write. | 
|. (XY) = Maximum number of bytes to write. 

1) = Path number. 


OUTPUT: (Y) = Actual number of bytes writter. 


C tit set. 


ERROR OUTPUT: (CC) : 
: (3) Appropriate error code. 


"ud 


This system call is sirilar to WRITE except it writes data untii 
a carriage return character is encountered. Line editing is also 
activated for character-oriented devices such as terminals, 
printers, etc. The line editing refers to auto line feed, null 
padding at end-of-line, etc. 


For. more. information atout line editing, see the section of this 
manual on "SCFMAN zn Editing Features . S | 
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WRITING RBF-TYPE DEVICE DRIVERS 


An RBF type device driver module contains a package of 


subroutines that perform sector oriented 1/0 to or from a 


specific hardware controller. These modules are usually 


reentrant so that one copy of the module can simultaneously . run. 
several different devices that use identical 1/0 controllers. 


. IOMAN will allocate a static storage area for eaca device (which 


may control several drives). The size of the storage area is 


given in the device driver module header. Some cf this storage 


t 


area will be used by. IOMAN and REFMAN, the device driver is free ~ 
to use the remainder in any way that it desires. This static. 


storage is laid out as follows: 


— Static Storage Definitions 


OFFSET ORG Y D 
N V.PAGE RMB 1 . PORT EXTENDED ADDRESS M 
1 V.PORT RMB 2 DEVICE BASE ADDRESS = 
3. V.LPRC RMB 1 LAST ACTIVE PROCESS ID 
4 V.BUSY RMB 1 ACTIVE PROCESS ID (@ = NOT BUST) 
5. V.WAKE RMB 1 PROCESS ID TO REAWAKEN © 
V.USER Son, END OF 0S9. DEFINITIONS | 
6 V.NDRV RMB 1 NUMBER OF DRIVES 
|». DRVBEG EQU BEGINNING OF DRIVE TABLES ` 
Gë TABLES RMB DRYMEM*N RESERVE N DRIVE TABLES 
FREE EQU . ede E TO USE 


NOTE: V.PAGE through V .USER are ee in ‘the OSSDEFS file. 
V.NDRV, DRVBEG, DRVMEM are predefined in the REFDEFS file. 


V.PAGE, V.PORT These three bytes are defined by IOMAN to be tne 
24 bit device address. 


V.LPRC This location contains the process-ID of the last. 
process to use the device. Not used by i as 
device drivers. 


Y.BUSY This location contains the process-ID P rues. 


process currently using the device. Defined ty 
REFMAN. | 
V.WAKE d This location contains the process-ID of any 


process . that is waiting for the device to 
complete I/G (9 = NO PROCESS WAITING). Defined by 
device driver. E | 
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OFFSET 


This location contains the number of drives that 
the controller will be worzing with. Defined by 


the device driver as the maximum number of drives 


thet the controller can work with. EBFMAN will 
assume that there is a drive tatie for each 
drive. Also see the driver ii routine in ae 
section. dÉ 


Res ma ze 


This area contains one IU for each: drive: that 
the controller will handle (REFMAN will assume 


thet there are as many tables as indicated : by 


V.NDRV). Some time after the driver INIT routine 
has beer called, RBFMAN will issue e request : for 
the driver to read the identification sector | 
(lcgicel sector zero) from a drive. At this 


time, the driver. will initialize- the - 
corresponding drive table by copying the first | 
part of the identification sector (up to DD.SIZ) 
into it. Also see the “Identification Sector' 


section of this manual. The format of each drive 
table is as given below: | | 


ORG 2 
DD.TOT RMB 3 TOTAL NUMBER OF SECTORS 
DO.TES RMB 1 TRACK SIZE ( IN SECTORS ) 
DD.MAP RMB 2 # BYTES IN ALLOCATION BIT MAP 
DD.BIT RMB 2 NUMBER OF SECTORS / BIT. 
DD.DIR RMB 3 ADDRESS OF. ROOT DIRECTORY. 

© DD.OWN RM? 2 OWNER’S USER NUMBER ` 

DD.ATT RMB 1 DISK ATTRIBUTES 
DD.DSX RMB 2 DISK ID | 
DD.FMI RMB 1 MEDIA FORMAT 
DD.SPT RMB 2 SECTORS/TRACK 
DD.RES RMB 2 RESERVED FOR FUTURE USE 
DD .S1Z EQU. 


 V.TRAK RMB 2 CURRENT TRACK NUMBER 
V.BMB RMB 1 BIT-MAP USE FLAG ` 
DRYMEM EQU . SIZE OF EACH DRIVE TABLE 


DD.TOT This location contains the total dontsés 
of sectors contained on the disk. . 


 DD.TKS This location contains the track size (in 


sectors). 


op HÄR This location contains the number of 


bytes in the disk allocation bit map. 
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DD.BIT This lccation contains the number of sectors that 


A each bit represents in the disk allocation bit 
| map. 
 DD.DIR This Ee contains the logical sector number 
of tne disk root directory. 
.DD.OWN This location. contains the disk owner’s user 
number. KR | | as 
- DD.ATT This location contains the disk access permission 
attritutes as defined below: 
BIT? =D (DIRECTORY IF SET) 
BIT 6 =S (SHARABLE IF SET) | 
BIT 5 = PX (PUBLIC EXECUTE IF SET) 
BIT 4 = PW . (PUBLIC WRITE IF SET) 
BIT 3 = PR (PUBLIC READ IF SET) 
BIT 2 =X (EXECUTE IF SET) 
BIT 1 =W (WRITE IF SET) 
BIT 2 =R (READ IF SET) 
DI .DSK This location contains a pseudo random number 
d | which is used to identify a disk so that 0S-9 may ` 
-— pp aee detect when a disk is removed fror the drive and. x 


another inserted in its place. 


DD.FMT DISK FORMAT: 


RIT BA - SIDE 
d = SINGLE SIZED 
= DOUBLE SIDED 


BIT B1 - DENSITY 
e 0 = SINGLE DENSITY 
DOUELE DENSITY 


1 


BIT B2 — TRACK DENSITY ` 
| @ = SINGLE (48 TPI) 
1 = DOUBLE (96 TPI) 


rd Number of sectors per track (track zero may use 
: a different value, specified by IT. TOS in the. 
device descriptor). ET | 


DD.RES RESERVED FOR FUTURE USE 


V.TRAK This location contains the BE track which 
the head is on and is. SEE bj the driver. 
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V.BMB This location is used ty REFMAN. to indicate 

whether or not the disk allocation bit map 

is currently in use (£ = not in use). The 

disk. driver -reutines must not alter this 
locatior. : E | 


Other Important Parameters 


Other parameters which may be important to device drivers ‘can 


found in the path descriptor. For a complete description of the 
values which are contained in the path descriptor, please see the 
section of this manuel on “REFMAN Definitions cf The Path 
Descriptor . Also see the section on device descriptors 
(especially the inittelizátion table). 


RBFMAN Device Driver Subroutines 


As with all device drivers, RBFMAN-type device drivers use a 
standard executatle memory module format with a module type of 
"device driver (CODE $E). The execution offset address in the 
module header points to a branch table that has six three byte 


entries. Each entry is typically @ LBRA to the corresponding ~ 


subroutine. The branch table is defined as follows: 


ENTRY LBRA INIT INITIALIZE DRIVE 
LBRA READ READ SECTOR 
LBRA WRITE WRITE SECTOR 
LEBRA  GETSTA GET STATUS 
LBRA SETSTA SET STATUS 
LBRA TERM TERMINATE DEVICE 


Each subroutine should exit with the DE code register € 
bit cleared if no error occured. Otherwise the C bit should be 
set and an appropriate error code returned in the B register. 
Below is a description of each STEE its input parameters, 
and Lis output PARAME tener 
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INIT n 
(U) = ADDRESS CF DEVICE STATIC STORAGE 
(Y) = ADDRESS CF THE DEVICE DESCRIPTOR MODULE 


OUTPUT: NONE | 
ERROR OUTPUT: (CC) = C BIT SET sa do a 


(B) = ERROR CODE 


FONCTION: INITIALIZE DEVICE AND ITS STATIC STORAGE AREA. 


1. If disk dee are verified, use the FSSRQM service 
request to allocate a 256 byte buffer area where a sector 
may be read back and verified after a write. 


2. Initialize the device permanent storage. For ` US 
disk controller typically this corsists of initializing 
V.NDRY to the number of drives that the controller will 
work with, initializing DD.TOT in the drive table .tc a 
non-zero value so that sector zero may be read or written 
to, and initializing V.TRAK tc $FF so that the first seek 
will find track zero. ` | | 


3. Place the IRQ service routine on the IRQ polling list 
ty using the OSS FSIRQ service request. 


4. Initialize the device control registers (enable 
interrupts if necessary). 


NOTE: Prior to being called, the device permanent storage 
will be cleared (set to zero) except for V.PAGE and V.PORT 
which will contain the 24 tit device address. The driver 
should initialize each drive tapie appropriately for the 
tyre of disk the driver. expects on the corresponding 


drive. 
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READ 
(U) = ADDRESS OF THE DEVICE STATIC STORAGE 
(Y) = ADDRESS CF THE PATH DESCRIPTOR 
(B) = MSE OF DISK LOGICAL SECTOR NUMBER 
(X) = LSB’s OF DISK LOGICAL SECTOR NUMBER 


SECTOR IS RETURNED IN THE SECTOR BUFFER 


C BIT SET 


(B) APPROPRIATE ERROR CODE 


FUNCTION: READ A 256 BYTE SECTOR 


Read a sector from the disk and piace it in the sector 
buffer (256 byte). Below are the things that the disk 
driver must dos. 


1. Get the sector buffer address from PD.BUF in the path 
descriptor. ; 


2. Get the drive number from PD.DRV in the path 
descriptor. 


Os Compute the physical disk address from the logical 
sector number. : V eig ; 


4. Initiate 1/0. 


5. Move V.BUSY to V.WAXE, then go to sleep and wait for 
the 1/0 to complete (the IRQ service routine is 


responsitle for sending a wake up signal). Af ter 


NOTE1: 


NOTE2: 


awakening, test V.WAKE to see if it CNE ss if not, go 
back to sleep. 


If the disk controller can not be interrupt driven it vill 
te necessary to perform programmed 1/0. 


Whenever logical sector zero is read, the first part of 

this sector must be copied into the proper drive table. 
(get the drive number from PD.DRV in the path descriptor). | 
The number of bytes to copy is DD.SIZ. 


The ae. number (PD. TRV) should te used to comrute the 
offset to the corresponding drive table as- follows: 


LDA PD.DRY,Y Get drive number ` 
LDB #DRVMEM | Get size of a drive table 


MUL 
LEAX DRVBEG „U Get address of first table 


LEAX D,X Compute address of table N. 


| 
| 
i 
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E, 
ed) 
r4 
+3 
tj 


ADDRESS CF THE DEVICE STATIC STORAGE AREA 
ADDRESS OF THE PATH DESCRIPTOR | 

MSB OF THE DISK LOGICAL SECTOR NUMBER. 
LSB’s OF THE DISK LOGICAL SECTOR NUMBER 


Pd 
HHH H 


HE SECTOR BUFFER IS WRITTEN OUT TO DISK 


ERROR OUTPUT: (CC) = C BIT SET 
| | (E) = APPROPRIATE ERROR CODE 
FUNCTION: VE SECTOR 


write the sector buffer (256 byte) out to the. disk. Below 
are the things that a disk driver must do: | 


1. Get the sector. buffer address from PD. BUF in the path 


| descriptor. 


2. Get the drive: number from PD.DRV in the path 


descriptor. 


KÉ Compute the physical disk address from the logical 
sector number. E MES ER l 


4. Initiate I/C. 


5. Move V.BUSY to V.WAKE, then go to sleep and wait for. 


the 1/0 to complete (the IRQ service routine is 


responsible for sending the wakeup Signal). After 


awakening, test V.WAKE to see if it is clear, if itis- 


not, then gc back to sleep. 


If the disk controller can not be interrupt driven, it 
will be necessary to perform programmed 1/0. he E 


6. If PD. VFY in the path descriptor is equal to zero, 
read the sector back in and verify that it was written 
correctly. This usually does not involve a compare of the 


data. 


If disk writes are to be verified, the INIT routine must 


Tequest the buffer where the sector may be placed when it 


NOTES: 


is read back in. Do not copy sector zero into the drive 
table when it is read back to be verified. 


Use the drive Ed (PD.DRV) to compute the offset to 
the corresronding drive. table as shown for the READ 
routine. 
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NAME: GETSTA 
^ PUTSTA 
INPUT: (U) 
(Y) 

(A) 


OUTPUT: (DEPENDS UPON 1HE FUNCTION CODE) 


ADDRESS CF THE DEVICE STATIC STORAGE AREA 
ADDRESS CF THE PATH DESCRIPIOR | 
STATUS CODE — 


ow H 


ERROR OUTPUT: (CO) = C BIT SET 
(B) = APPROPRIATE ERROR CODE 


FUNCTION: GET / SET DEVICE STATUS 


These routines are wild card TOES used tc get (set) the 
device’s operating parameters as specified for the OSS 
I¿GSTT and I$SSTT service requests. The codes passed to 
the device driver are given below: 


GETSTAT: Any I$6GST T function code not defined by Microware 
 SETSTAT: SS.RST (code 3) = Restore head to track zero. 

SS.WRT (code 4) = Write track. 

Any ISSSTT function code not üefined by e 
It may be necessary to examine or change the register 
stack which contains the values of MPU registers at the 
time of the I$GSTT or I$SSTT service request. The address 
of the register stack may be found in PD.RGS, which is 


located in the path descriptor. The following offsets may 
be used to access any particular value in the Eh 


stack: 
OFFSET | NMEMONIC | MPU REGISTER 
$0 E | RMB 1 CONDITION CODE REGISTER. 
Si R$D EQU . D REGISTER — 
$1 RSA RMB 1 A REGISTER 
i: | R$B RMB 1 B REGISTER 
3 RSDP RMB 1 DP REGISTER 
$4 RSX RMB Z X REGISTER 
E SH RMB 2 Y REGISTER 
>8 RSU RMB 2  U REGISTER 
SA RPC RMB 2 PROGRAM COUNTER 
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NAME: — TERM | | | 
INPUT: (U) = ADDRESS CF DEVICE STATIC STORAGE AREA 
-QUTPUT: NONE | "Td 


ERROR OUTPUT: (CC) = C BIT SET S 
(B) = APPROPRIATE ERROR CODE 


. FUNCTION: ` TERMINATE DEVICE 


| This routine is called when a device will no longer be 
needed in the system (when the link count goes to zero). 
The primary things that it does are: 


1. Wait until any pending 1/0 has completed. 

2. Disable the device interrupts. 

3. Remove the device from the IRQ polling iist: 

4. If the INIT routine reserved a 256 byte buffer for 


verifying disk writes, return the memory with the FSMEM 
service request. uL E e LN ee 
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Although this routine iS. rot included in the device 
drivers branch table and not called directly from RBFMAN, 
it is an importent routine in device drivers, The main. 
things that it does are: 


de Service device interrupts. 


2. When the I/O is complete, the IRQ service routine 
should send a wake up Signal to the process whose process 
ID is in V.WAKE 


Also clear V.WAKE es a flag to e program that 
the IRQ has indeed occurred. 


NOTE: When the IRO service routine finishes servicing an 
interrupt it mst clear the carry and exit with an RTS 
instruction. 
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WRITING SCF-TYPE DEVICE DRIVERS 


An SCFMAN-type device driver module contains a package of 
subroutines that perform raw I/O transfers to or from a specific 


hardware controller. These modules are usually reentrant so that 


one copy of the module can simultaneously run several different. 


devices that use identical . I/O controllers. For each 


‘incarnation’ of the driver, IOMAN will allocate a static storage 
area for that device. The size of the storage area is given in 
the device driver module header. Some of this Storage area will 
be used by IOMAN and SCFMAN, the device driver is free to use the 
remainder in any way it desires (typically as variables and 
buffers). This static storage is laid out as given telow: .... 


STATIC STORAGE DEFINITIONS 


OFFSET ORG Ø | Bu 
$8 V.PAGE RMB 1 PORT EXTENDED ADDRESS 
$1 V.PORT RMB 2 DEVICE BASE ADDRESS -` O re 
$3 V.LPRC. RMB 1 LAST ACTIVE PROCESS ID eee 
$4 V.BUSY RYB 1 ACTIVE PROCESS ID (@ = NOT BUSY) 
$5 V.WAKE RMB 1 PROCESS ID TO REAWAKEN | 
V.USER ECU . END OF OS9 DEFINITIONS 
$6 V.TYPE RMB 1 DEVICE TYPE OR PARITY | s 
$7 V.LINE RMB 1 LINES LEFT TILL END OF PAGE 
$8 V.PAUS RMB 1 PAUSE REQUEST (Ø = NO PAUSE) 
$9. V.DEV2 RMB 2 ATTACHED DEVICE STATIC STORAGE 
$3 V.INTR RMB 1 INTERRUPT CHARACTER ` 
oC V.QUIT RMB 1 QUIT CHARACTER: 
$D V.PCER RMB 1 PAUSE CHARACTER 
$E V.ERR RMB 1 ERROR ACCUMULATOR 
$F V.SC?* EQU . END OF SCHAN DEFINITIONS. 


FREE EQU . FREE FOR DEVICE DRIVER TO USE 


V.PAGE, V.PORT These three bytes are defined by IOMAN to be the 


¿4 bit device address. 


Y.LPRC a This location contains the process-ID of the last 


process to use the device. The IRQ service 
routine is responsible for sending this process 


the proper signal in case a QUIT character or . 


an “INTERRUPT” character is recieved. Defined by 
SCFMAN. ) j 
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VERR ^ ^. This location is used to accumulate I/O errors. 


Typically it is used by the IRQ service’ routine | 
^to record errors so that they may be reported 
later when SCFMAN calls one of the device driver 
routines. | P 


.-.SCFMAN DEVICE DRIVER SUBROUTINES 


As with all device drivers, SCFMAN device drivers use a standard. 


executable memory module format with a module type of “device 


driver’ (CODE $E). The execution offset address in the module 


header points to a branch table that hes six three byte entries. 


Fach entry is typically a LBRA to the corresponding subroutine. 


The branch table is as follows: 


ENTRY LERA INIT INITIALIZE DEVICE 
LBRA READ. READ CHARACTER 
LFRA WRITE WRITE CHARACTER 


LBRA GETSTA. GET DEVICE STATUS 

LBRA SETSTA SET DEVICE STATUS 

LBRA TERM. TERMIN TE DEVICE 
Fach subroutine should exit with the condition code. register C 
bit cleared if no error cccured. Otherwise the C bit should be 


set and an appropriate error code returned in the B register. 
Felow is a descripticn of each subroutine, its input parameters 


and its output parameters. | 
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NAME: INIT | Sech Zi PR | 1 ee 


INPUT: (U) = ADDRESS OF DEVICE STATIC STORAGE gn. dle 
(Y) = ADDRESS OF DEVICE DESCRIPTOR MODULE TU 


OUTPUT: NONE 


ERROR OUTPUT: (CC) = C BIT SET 
(8) = ERROR CODE 


FUNCTION: — INITIALIZE DEVICE AND I™S STATIC STORAGE 


1. Initialize the device static storage. 
2. Place the IRQ service routine on the IRQ 
polling list by using the 059 FSIRQ. service 
request. e N 


De Initialize the device control registers 
{enable interrupts if necessary). 


NOTE: Prior to being called, the device static 

storage will be cleared (set to zero) except for 
V.PAGE and V.PORT which will contain the 24 tit 
device address. There is no need to initialize 

the pertion of static storage used by IOMAN and 
SCFMAN. | m | | 
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) i 


(N NAME: READ 
INPUT: (U) = ADDRESS CF DEVICE STATIC STORAGE 
(Y) = ADDRESS CF PATH DESCRIPTOR 
OUTPUT: (A) = CHARACTER READ 
ERROR OUTPUT: (CC) = C BIT SET 
] (B) = ERROR CODE p 
FUNCTION: GET NEXT CHARACTER 
This routine should get the next character from 
the input buffer. If there is no data ready, 
this routine should copy its process ID from ` 
V.BUSY into V.WAKE and then use the FSSLEP . 
service request to put itself to sleep. 
Later when data is recieved, the IRQ service 
routine will leave the data in a buffer, then 
check V.WAKE to see if any process is waiting for 
the device to complete 1/0. If so, the [RO 
service routine should send a wakeup Signal to 
Q | : AE E NOTE: Data ` buffers _ are NOT automatically + 


allocated. If any are used, they Should be 
defined somewhere in the device’s static storage 
area. | 
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NAME: WRITE 


-INPUT: (U) = ADDRESS CF DEVICE STATIC STORAGE 
© (Y) = ADDRESS CF THE PATH DESCRIPTOR 
= CEAR TO WRITE 


OUTPUT: NONE 


ERROR OUTPUT: (CC) = C BIT SET 
, (B) = ERROR CODE 


FUNCTION: OUTPUT A CHARACTER 


This routine places a data byte into an output 
buffer and enables the device output interrupts. 
If the data buffer is already full, this routine 
should copy its process ID from V.BUSY into 
V.WAKE and then put itself to sleep. | 


Later when the IRQ service routine transmits a 
character and makes room for more data in the 
buffer, it will check V.WAKE to see if there is a 
process waiting for the device to complete I/O. 
If there is, it will send a wake up .Signal to 
that process. no NEC o 


Note: This routine must ensure. that the IRO 
service routine will start up when data is placed 
into the buffer. After an interrupt is generated 
the IRQ service routine will continue to transmit 
data until the date buffer is empty, and then it 
will disable the device’s "ready to transmit’ 
interrupts. l 


Notes. Data buffers are NOT automatically 
allocated. If any are used, they Should be 
| defined somewhere in the device’ s static storage. 


| 
| 
| 
| 
| 
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NAME:  GETSTA. 


SETSTA 


ADDRESS CF DEVICE STATIC STORAGE 
ADDRESS OF PATE DESCRIPTOR 
STATUS CCDE 


INPUT: (U) 
(Y) 
(A) 


uU ug dg 


OUTPUT: ( DEPENDS UPON FUNCTION CODE ) 


FUNCTION: GET / SET DEVICE STATUS 


This rcutine is a wild card call used to get 
(set) the device parameters specified in the 
I$GSTT and I$SSTT service requests. Currently 
all of the function codes defined by Micrcware | 
for SCF-type devices are handled by IOMAN or- 
SCFMAN. Any codes not defined ty microware will 
be passed to the device driver. | 


It may te necessary to examine or change the 
register packet which contains the values of the 
68909 registers at the time the 0839 service 
request was issued. The address of the register 
packet may tbe found in PD.RGS, which is located 
in the path descriptor. The following offsets 
May be used to access any particular value in the 
SE eeh 


OFFSET NMEMONIC MPU RECISTER 


$0 R$CC RMB 1 CONDITIONS CODE REGISTER. 
SE v RSD EQU . D REGISTER 

$1 RSA RMB 1 A REGISTER 

$2 R$B RMB 1 B REGISTER 

$3 RSDP RME 1 DP REGISTER 

$4 RSX RMB 2 X REGISTER 

$6 . R$Y RMB 2 Y REGISTER 

$8 R$U RMB 2 U REGISTER. 

2 PROGRAM COUNTER 


$A R$PC RMB 
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NAME: TERM 
INPUT: (U) = PTR TO DEVICE STATIC STORAGE 
OUTPUT: NONE | 


C bit set 


ERROR OUTPUT: e 
Appropriate error code 


"on 


(CC) 
(3) 


- FUNCTION: TERMINATE DEVICE 


This routine is called when a device will ro 
longer be needed (when its link count goes to 
zero). The main things that it does are: ` 


1. Wait until the output buffer has been emptied 
(by the IRQ service routine). | 


2. Disable device interrurts. 


3. Remove device from the IRQ polling list. 


NOTE: Static storage used by device drivers is 
never returned to the free memory pool. =c 
Therefore, it is desirable to NEVER terminate any  " 
device that might be used agair. Modules 
contained in the BOOT file will NEVER te 
terminated. j SR 
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AN NAME: IRQ SERVICE ROUTINE 


FUNCTION: © SERVICE DEVICE INTERRUPTS. 


Although this routine is not included in the 
device drivers branch table and not called 
directly from SCFMAN, it is an important routine 
in device drivers. The main things that it does 
are: . 


1. Service the device interrupts (recieve data 

from device or send data to it). This routine 

should put its data into and get its data from 

buffers which you have defined in the device 

. Static storage. | EEN 
| 


2. Wake up any process waiting for I/O to. 
complete ty checking to see if there is a process 
ID in V.WAKE (non-zero) and if so senda wakeup 
signal to that process. 


d. If the device is ready to send more data and 
the output buffer is empty, disable the device ^s 
'ready to transmit" interrupts. : 


; 4. If a pause character is recieved, set V.PAUS 
ÜN "S in the attached device static storage to a nor- 


static stcrage is in V.DEV2. 


When the IRQ service routine finishes servicing 
an interrupt, it must clear the carry and exit 
with an RTS instruction. 
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OUTPUT: (D) 
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WRITING. A SYSTEM BOOTSTRAP MODULE. 


The bootstrap module contains one subroutine that loads tae 


»bootstrep file and some related information into remcry. It uses 
the standard executable module format with a module type cf 


‘system (code $C). The execution offset in the module header 
contains the offset to the entry point of this subroutine. The 
following section describes the parameters passed tc the the BOOT 


-Toutine and its function. Also see the sections of this manual 


on "Writing RBF- type. Device Drivers end ‘Logical and Physical ` 


Disk Organization . 


INPUT: None. 


H 


SIZE OF TEE BOOT FILE (in bytes) 
ADDRESS CF WHERE THE BOOT FILE WAS LOADED IN MEMORY 


i 


ERROR OUTPUT: (CC) = C BIT SET. 
(B) = APPROPRIATE) ERROR CODE 


FUNCTION: LOAD THE BOOT FILE INTO MEMORY FROM MASS-STORAGE 


This routine atterpts to load the bootstrap file into 
memory from a mess-storage device. Tyrically it will read 

some form of identification block which will contain the 

location and size of the bootstrep file. OS-¢ is called 

to allocate a memory area large enough for the boot file, 
and then it loads the boot file into this memory area. 
Below is a description of how this is done for RBFMAN-tyre 
devices (DISK): 


4. Read the identification sector (sector zero) from the 
disk. 2o05 must pick its own buffer area. 
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The identification sector contains the values for DD.BT 


(the 24 bit logical sector number of the bootstrap file), 


and ID.FSZ (the size of the bootstrap file in bytes). For 


a full description of the identification sector, please 
see the section on . Physical and Logical Disk 


Organization i 


2. After reading the identification sector into the 
puffer, get the 24 bit logical sector number of the 
tootstrap file from DD.3T. - | | 


3. Get the size (in bytes) of the bootstrap file from | 


-DD.BSZ. The boot is contained in one logically contiguous | 


block teginning at the logical sector specified in DD, BT - 
and extending for ( DD. 52/256 + 1 ) sectors. FR 


4. Use the OSS F$SROM service request to EE 


memory area where the boot file will be loaded into... 


5. Read the boot file into this memory area. 


6. Return the size of the toot file and its location. 
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EXECUTABLE MEMORY MODULE FORMAT 


aij aie ara ae ee aae a aan aae aee aene YD ami- omr nen SS amar miae a ER Re ens a ny ne err + dm om t 
! ! 
qe Sync Bytes ($87CD) + 
l Ge ! 


N | Dc 


+= Module Size (bytes) -— 
! BE 
R——————————À—Ó— — M M MÀ À nw nen ae * 
A ! 
re Module Name Offset SE 
! f 
rem À — — 9 À M  — M ne ee a ee + 
1 Type ! ponerme LE. 


je emm anm a anre same emm mee aa» epp oae GR UU ep: QU gem o A e gr GP "A. an ie un ante E 


! Attributes ! Revision KE: 


TEE OT en ——Ó— dl 
EZ ww Header Perity Check NE 
TERE SERE E + 
1 ! 
== Execution Offset Ee 


Ee SE | ! 


! & E 


+=- Permanent Storage Size --+ 
RUE Woo oe ! 


1 


(Add^1 optional header 
extensions located here) 


e o LÀ e e € e * 6 


: Module Body l 
object code, constants, etc. 


E ae cee MÀ meme M ome am ae —— e + 
Do ! 
se et 
1 CRC Check Value 1 
dee sd 
D f 
ES ome — eae aa ma ame aee, mem aee À me nem —À MÀ—À  —À + 


(C) 1982, 1981 Microware Systems Corporation 


Om 9 0m 6o 070 Gap 00% New Zap go Gap 


em wi: opt ar MEE QUI. HEEN, sët 


Kong ` dag Om DR Om om oam Zog gang dd 


oe sam gu go OM OP OM Zon pont fg gon got sa om re Ak 


om 


+ (am OM om OP Ren em de fo PAN DAE ga gang nem gab OE ou DEE gen HD Ca Gm gn 59 mm 


emm em gu UU QUUM. dr e DP UP aer E op 


add 


ae. AED anie 
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DEVICE DESCRIPTOR MODULE FORMAT 


l ! 
! 


! | | ! 


* 


a e À— M HÓ— M — M À ee 
! 1 
4—— Offset to Module Name | --+ 
f l ! 


pres es mme em wm. ap AS d EE e et eg weg gf io SOR vm Er em bz 


| åF (TYPE) y. $1 (i ANG)  ——! 
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ence a ar ee ee ee ee eee se a ae a me MÀ À— MÀ me + 
! Header Parity Check | e 


! | dë E 


*-—- Offset to File Manager --+ 


! Name String — | 


. +=- Offset to Device Driver --+ . 


Ls | Name String ! 
4------------2-----—-—-—--------- + 
! | Mode Byte ! 
pe te ne ae ee ee —— ee a en À MÀ À — ——À + 
! | | | | l 
-—— | Device Controller: -—4 
l. Absolute Physical Address ! 
ees (24 bit) ` | eed 
l EG j 1 
A er a + 
! Option table Size 1 
R—— M —À———— — a ae ÀÓ—— —— MÀ -+ 


Dees Table) 


! 
f 
| | ! 
e e e e + © e e © gf e © * U 
! f 
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l 


! 
I 
l 
! 
! 
l 
E 
+ 
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! CRC Check Value E 
Po Ñ a «$» 


ME DE : | | d 


+-- Syne Bytes (587CD) mm 
| ! 


*—— Module Size (bytes) EE 
! 


"m MP 
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$01 
$g2 


CONFIGURATION MODULE FORMAT 


! | | ! 


4 # IRQ Polling Terle Entries ! 


! # Device Table Entries ! 


ho Sync Bytes ($€7CD) -—* 
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SINGLE DENSITY aoe DISK FORMAT 


(FORMATTED ) 


(e) ede 


$e 


SIZE 5 
DENSITY SINGLE 
- 8TRACKS 35 
#SECTORS /TRACK 1£ 
BYTES/TRACZ 3125 
(UNFORMATTED) 
FORMAT #BYTES VALUE 
(DEC (HEX) 
^- HEADER 39 EE 
(ONCE PER TRACK) 6 02 
| 1 FC 
12 FF 
SECTOR 6 00 
(REPEATED N TIMES) 
d (TRK +) 
1 (SIDE #) 
1 (SECT #) 
1 —(BYTCNT) 
i. y? (2 CRC) 
12 EF 
6 99 
1 FB 
256 (DATA) 
1 FP? (2 CRC) 
16 FF , 
TRAILER 96 FF 
(ONCE PER TRACK) | 
BYTES/SECTOR 256 
(FORMATTED) | | 
BYTES /TRACK 2560 
(FORMATTED) 
BYTES/DISK 89,600 


SINGLZ 
77 


ABYTES VALUE 
(DEC) (HEX) 


KI FF 
E Ze 
1 FC 
12 EF 
e 0g 
L FE 
1 (IRK +) 
1 (SIDE $) 
Y (SECT +) 
1 (BYTCNT) 
1 F7 (2 CHC) 
19 FF 
6 90 
o d Fa 
256 (DATA) |. 
1 F7 (2 CRC). 
12 FF 
391 FF 
256 
4296 
315,292 
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DOUBLE DENSITY FLOPPY DISK FORMAT 


SIZE ` 


(C) 1989, 1981 Microware 


5 
DENSITY DOUBLE 
#TRACKS 35 
 8SECTORS/TRACK 16 
BYTES/TRACE 6259 
(UNFORMATTED) — 
FORMAT BYTES VALUE 
(DEC) (HEX) 
HEADER | 80 AX 
(ONCE PER TRACK) 12 ee 
3 F5 (A1) 
1 POE is 
32 45 
SECTOR 12 20 
(REPEATED N TIMES) 3 Së 
l FE 
1 (TRE 4) 
1 (SIDE +) 
1 (SECT ai 
1 (BYTCNT) 
1 F7 (2 CRC) 
22 AE 
12 go 
3 FS (A1) 
1 F3 
256 (LATA) 
1 F? (2 CRC) 
22 4k 
TRAILER = eps 4i 
(ONCE PER TRACK) 
BYTES /SECTOR 256 
(FORMATTED ) | 
 BYTES/TRACK | 4096 - 
(FORMATTED) 
BYTES/DISK - 141,824 
(FORMATTED) 


E-Z 


LA 


8 
DOUBLE 
77 
28 
19,416 
BYTES VALUE 
(DEC) (HEX) 
80- 4E 
12 DL 
3 F5 
1 FC 
32 4E 
12 20 
3 M aee) 
1 FE 
Sé (TRK #) 
1 (SIDE +) 
i (SECT #) 
1 (3YTCNT) 
1 E7 (2 CRC) 
22 LE 
12 9 
3 FS (A1) 
1 FB 
256 (DATA) 
E F7 (2. CRC) 
22 “E 
768 4E. 
256 
7168 


548,864 - 


MEE EA 


L 


| 0S-9 LEVEL ONE SYSTEM PROGRAMER’S MANUAL 
Appendix F: Sample Assembly language Programs - CLOCK 


SEERA SEAR AC AACE AC A RAO AREA E E 
x* | | 
= CLOCK MODULE FOR THE MPT TIMER | | ia 


j (c) 1981 Microware Systems Corporation | - 8 


RE EE EE ea a aK a AAO Ge A 


NAM Clock Module 
TTL Definitions. 
Use /40/defs/syStype 
opt =C 


OK ae e SE ak ae ae akc ale ekee de de ac eae a ae K ae ak ae 


»* System Type Definitions * 
34 oj ak ah ak a ae ae ok a ak ake ae a ak ale 2t oe de SK RE a ee ae a 


CPUTYP SET GIMIX CU type 
4 DSKTYP SET DC bé Disk Controller type 
CLKTYP SET | MPT Clock type 
c INTRPT SET YES | Interrupt Driven Disk Flag 
. DRVONT SET 4 Number of Drive Descriptors 
^ DRVSIZ SET 8 | Drive size 


REV | SDT a . Revision Level 


ee. MRK AK I ACA see c 


Disk Port Address . > 
de 


DPORT SET e 
DPORT SET SE6C2 


BE Ne S ake o oe ae ae ae o a a IE ah ae ooi zt ERO d da de OK 


* Clock Port Address  ¥* 
———— a ae se ake de ah ae de die 


CPORT SET Ø 
CPORT SET ¿1259 


Bit ote ole Oe o ote de BEE e ee AO de e HE OE EE 


* I/O Port Addresses * 
II ote she she ake de aie aie de ake ake ae e e de BIg ae dr A e OKR 


A.TERM SET $EGO4 | ACIA Ma ber Terminal 


A.T1 SET. $582  aCIA Secondary Terminal 
A.P SET $049 PIA Printer (3-side) 
PIASID set a.side ` js ME 
A.P1 SET $038 ACIA Printer 

opt c | | | 


opt ec Ae | 


©- (C) 1988, 1981 Micrdware Systems Corporation 
| | SCH Ee 


oe MODULE HEADER * 


OS-O LEVEL ONE SYSTEM PROG: 


AMER'S MANUAL 
Appendix F: Sample Assently Langue Pro 


y laze Programs - CLOCE 


E sh ae ak ak ak ae ak ae ECTE da dete a ak tote sk ak 


DÉI 


ELI: RR dk BK ie Ed RIA de OS GR S OAS BERE BE AE 


Type . SET . SYSTM+OEJCT 

Revs SET | REENT «41 

CikMod Mod Clkind, ClkNam, Typ€, REVS, ClkEnt, CPORT | p 

ClkNam = FCS (isen! | S | x 
FCB Edition number | 

CLEPRT EQU MESTAX Stack has Clock Port address. 


MM RR x ake a abe oic ake dek AR RE XO AE OK a a RR AX IE 


.* CLOCK DATA DEFINITIONS * 
MEE IK oe o ie de AK ie BE AE sic c HE Oe OE BK OK dees SCENE 


TIMSYC FCB  FSTIME 
FDB | TIME-*-2 
FCB $80 


skate ak aj ak sje sje ote ak ak de de ait code aste ak ak REIKI AO dek 
* DAYS IN MONTES TABLE * 
RR EK ats a zi ote ak ak af ote x a aeo ais te ate Bede ake ak 


MONTES FCB o | UNINITIALIZED MONTE 


FCB 31 JANUARY 
FCB 28 FEBRUARY 
FCB 31 | MARCH 
FCB ae APRIL 
FCB A1 MAY 

FCB 38 JUNE - 
FOR. 31 JULY 

FCB 31 AUGUST 
FCB 30 SEPTEMBER ` 
FCB 31 OCTOBER 
FCB 30 NOVEMBER 


FCB S | DECEMBER 


sek a abc abe ake ofc ahs aft de ee afc de iE ELE I ër ée RE NE A A 


* CLOCK INTERRUPT SERVICE ROUTINE * 
Ee PER 


NOTCIK MP. [D.ISVC] O TO INTERRUPT SERVICE 
CLOCK ADDRESS 


G 

 CLKSRV LDX CLEPRT, PCR G 
T | | GET CONTROL REGISTER 

I 

P 

C 


LDA X 
BITA ein 
-BEQ  NOTCLK 


S IT CLOCK? 
RANCH IF NOT - 
LEAR CLOCK INTERRUPT 


LIDA £,X 
FICK CLRA — SET DIRECT PAGE 
TER — A,DP 


(C) 198€, 1981 Microwere Systems Corporation 


rre 


esa ak a a 
* -UP 


TICK10 


TICK15 


TICK29 ` 


TICK25 


| TICKZ2 
TICK35 


TICKS ` 


 0S-9. LEVEL ONE 
ndix F: 


See A A de AES ee IG 
m 


Ds CURRENT 


Sample Assembly 


x 
1 


SYS 


TEM PROGRAM 
La a 


COUNT TICK 


BRANCH IF NOT END OF SECOND 


GET MINUTE & SE 
COUNT SECONL 
END OF MINUTE? 
BRANCH IF NCT 
COUNT MINUTE 
END OF HOUR? 


GOND. 


BRANCH IF NOT 


GET DAY & ECUR 


. COUNT HOUR 


FCR 


DEC Dt 
BNE TICKSS 
LDD D.MIN 

INCB 
CMPB #62 
PCS TICKSS 
INCA 
CMPA #60 
ECS TICKS@ ` 
LDD D. DAY 
INCB 
CMPB #24 
RCS TICK25 
INCA 
LEAX MONTHS, 
LIB D.MNTE 
CMPB #2 
BNE TICK192 
LDB D.YEAR 
BEQ TICK12 
ANDB #2 
BNE TICK12 
-DECA 
LDB D.MNTH 
CMPA P,X 
BLS "ICK20 
LDD  D.YFAR 
INCBS- 
CMPB'^ #13 
BCS TICK15 
INCA 
LDB +1 
STD T.YEAR 
LDA #1 
CLRB - 
STD D.DAY 
CLRA 
| CLRB 
STD . D.MIN 
LDA T.TSEC 
STA D.TIC 
JMP [CLOCK] 
(C) 1989, 1981 


END OF DAY? 

BRANCH IE NCT 

COUNT DAY 

GET DAYS/MONTH TABLE 
GET MONTH 

IS IT FEBRUARY? 
BRANCH IF NOT 

GET YEAR 

BRANCH IF EVEN HUNDRED 
IS IT LEAP YEAR? 
BRANCE IF NOT 

ADD FEB 29 © 

GET MONTH 

END OF MONTH? 

BRANCE IF NOT 

GET YZAR & MONTH 
COUNT MONTH 

END OF YZAR? 

BRANCH IF NOT 

COUNT YEAR 

NEW MONTE | 

UPDATE YEAR & MONTH 
NEW DAY 

NEW HOUR. 

UPDATE DAY & HOUR 
NEW MINUTE 

NEW SECOND 

UPDATE MINUTE & SECOND 
GET TICKS/SECOND 


td 


CO TO SYSTEM CLOCK ROUTINE 


Microware Systems. ‘Corporation 


F-3 


 ClkEnt 


-05-9 LEVEL ONE SYSTEM PROGRAMER/S MANUAL 


Appendix PF: 


Sample Assembly Language Programs - CLOCK 


sic x o de OE c otc o MOE ale sic BK ak zc a oie De de sje ee he SE p a ie ae aK 


Polo: DE 
CLRA 

TER A,DP 
PSES. CC. 
LDA #12 
STA D.TSEG 
STA D.TIC 
LDA #1 


STA D.TSLC 
STA  D.SLIC 


ORCC 
LEAX  CLKSRV,FCR 
STX  D.IRQ 
LDX  CLKPRT,PCR 
CLRA 
CIRB 
STD Ø,X 
LDD #SFESD 
STD £,X 
LDD #58005 
STA  £,X 
STB  £,X 
LDA @,X 
PULS CC 
LEAY TIMSVC,PCR 
0S9  F$SSVC 
PULS DP,PC 


ate sic de aie ake akc atc aft a akc ake de de de de dee ot MEE de BAK aK 


* SUBROUTINE TIME  * 


* (RETURN TIME OF DAY) * 
LI ak die ak de ak afc akc He de ae TIPS akc aie AE ae ee e ge we 


TIME EQU * 


LDX  R$X,U 
LDD  D.YEAR 
STD ot 
LDD  D.DAY 
STD  2,X 
LDD  D.MIN 
STD 4,X 
CLRE 

RTS 

EMod 

 ClkEnd FIQU * 
| END. 
(C) 1980, 1981 


* CLOCK INITIALIZATION ENTRY * 


o AN Ye INES AS SG OAR YE OG AR OR OE OK GO ball oy OE AE ACAD SK AK ME OK 


save Direct Page. 
clear DP 


save interrupt masks 
SET TICKS / SECOND. 


SET TICKS (IME SES 


SIRQM4FIRGQM SET INTRPT MASKS 


GET SERVICE ROUTINE 
SET INTERRUPT VECTOR 
get clock address 


CLEAR PIA REGS. 
INITIALIZE CLOCK BOARD 


CLEAR ANY INTERRUPTS 
retrieve masks ! 


SET TIME SEVICE ROUTINE 


Get Specified location 
Get Year & Month 


Get Day & Hour 


SE? Minute & second 


Clear Carry 


Microware systems corporation 


C 


"009 LE 


Appendix F: 


* 
* 
* 
+ 


Y 
sê 


EL ONE SYSTEM PROGR 
mpie Essembly language ? 


TERM ~- Device Descriptor Module 
(C) 1981 


Microware Systems Corporation 


&MER/S MANUAL | 
rograms - TERM 


six a ak ak it Ne ak ak ad a oleo —— KERR EERDER KERE RE DE EER EE PER EE IE 


HW HH 


EE IS 


mod 


feb 


fcb 


. fdt 


fcb ` 
fcb 


A.TERM 


TRMNAM-*-1 


DT.SCF 


* DEFAULT PARAMETERS 


TRMNAM 
TRMMGR 


TRMDRY 


TRMENL 


fcd e 

fcb 1 

fcb oO: 

fcb 1 

fcb 1 

fcb ð 

Zen 1 

fcb 24 

fcb CSESP 

fcb CSDEL 

fcb C$CR 

fcb CS EOF 

fcb CSRPRT 

fcb CSRPET 

Zen CSPAUS 

fcb | CSINTR 

feb | C$QUIT 

fcb Je 

fcb CS BELL 

fcb $15 
feb D 

fdb TRMNAM 

fcs „TERM 

fes Se " 

fcs ACIA 

emod 

EQU x 

(C) 1988, 1981 


. TRMEND, TRMNAM,D DEVIC+OBJCT, REENT+1, TRMMGR, 


mode 


port addresss 
option byte count. 
Device Type: SCF 


case=UPPER and lower 
backspace=BS,SP,3BS 


delete=backspace over line 


auto echo on 

auto line feed on 
null count 

end of page pause on 
lines per pege 


backspace char 


delete line char 
end of record char 
end of file char 
reprint line char 
dup last line char 
pause char. | 
Keyboard intersapt char 
Keyboard Quit char 
tackspace echo char 
line overflow char 

no parity 
undefired baud rate 
offset of echo device 
device name 

file manager 
device driver 


Module CRC 


 Microware Systems Mn por ES 


pem 


0S-9 LEVEL ONE SYSTEM PROGRAMER’S MANUAL 
 &ppenüix F: Sample Assemtly Language Programs ~ ACIA 


IG fe Be I P P E EK aK ee A ERE ORR A A 


Y a 
Kë JACIA - Interrupt Driven ACIA Device Lriver * 
* | (C) 1981 Microware Systems Corporatior ck 
* : | x: 


aate ae a aj He abe oe te ak ze oben oe o s ac a af a aha ake ak ake a le tee ote ak tete Rd ste 9K ais oe wk ae xe afe ate a oe ace ak a ate ea a HR 


ONAM ACTA | 
ifpi 
endc d0/defs/scfdefs 
INPSIZ set 10€ input buffer SIZE (4-256) 
OUTSIZ set 40 output buffer SIZE (42256) — 
PARITY set  Z01€00000 parity error bit 
-© OVERUN set 208102028 overrun error bit 
FRAME set — Z000100€0 framing error bit 
NOTCTS set | &0000100€0 not clear to send 
. DCDLST set ¿606068601022 data carrier lost 
PARITY +OVPRUN+FRAME+NOTOTS +DCDLST 


INPERR set. 


————— 


e Static storage offsets * 
Red 


room for SCF variables 


ste ale ole otc ate ale afc afc ape ais aie ae aie dee MEIC NE AE DC IK opere seo x 


* MODULE HEADER 
ate ae fea aa al leote ak ak ake ACK a aK a aR a ` 


ACINAM 


jx ae oe zie ake fe afc ate abe af ake ake de die ak hr de ak ae ake ak sole ak ae o 
BRANCH TAELE 


OX 


MOD 
FCB 
FCS 


feb 


* 


ORG V.SCF 
INXTI RMB 1 input buffer NEXT-IN ptr- 
INXTO RMB Use input  tuffer NEXT-OUT pir. 
ONXTI RMB 1 output buffer NEXT-IN ptr 
ONXTO RMB 1 deo NEXT- QUT ptr 
INPBUF RMB INPSIZ input buffer ` 
OUTBUF RMB OUTSIZ output buffer 
ACIMEM | EQU . TOTAL STATIC STORAGE REQUIREME 


ACIEND, ACINAM, DRIVR4OBJCT, [REENT+1, ACIENT 


UPDAT. 
"ACIA' 


2 


* 


exl le oy oe e tete a8 ae te ae de xa a ac ak ak ale xc ak ae ak a a 


 editiion number 


ACIENT LBRA INIT 

| LBRA READ 
LPRA WRITE 
LBRA GETSTA 
LIBRA PUTSTA 
LERA  TRMNAT 
(C) 1982, 1981 


> Microware Systems ed LUN 
F-8 | 


ES 


d 


ACMASK - 


^. 08-9-LEVEL 
Appendix F: Sam 


FCB 


FCB 
SCH 


GRAMER'S MANUAL 


ONE SYSTE Dub 
i guage Programs. SS ACIA 


e inis 


Bo 


a 
iL 
* 

Lc 


e no FLIP bits ; 
8e. IRO. POLLING MASK 
5 (low) PRIORITY 


bh RR RE ae ake ae ak aa ake oj te oe ot Mede a ak ak ak sol 


* INITIALIZE (TERMINAL) ACIA * 


INIT 


INITIO 
INIT20 


INITZO 


INITO 


LDX 
LDB 


STB 


LDA 
CMP A 
BLO 
EE 
BNE 
LDB 
STB 
LDL 
LEAX 
LEAY 
0S9 
BCS 


LRA 


CLRB 
STD 
STD 
LDX 
LDB 
ORB 

STB 
RTS 


e akaki e aeee XO A e K RR E KRKK C | 


V.PORT,U | I/O port address 

#523 master reset signal 
LX reset ACIA 

MSOPT,Y get opticn byte count 


#HPD.PAR-PD.OPT acia control value given? 


INIT10 uM default $15 
PD.PAR-ID.CPT«M$DTYP,Y | 

INIT29 

$15 default acia control 

V.TYPE,U save device type 

Y.PORT,U 

ACMASK, PCR i o | Bee 
ACIRO,PCR address of INTERRUPT SERVICE R 
F$IRO ADD to IRQ POLLING TABLE l 
INITS ERROR - return it 


INXTI,U INITIALIZE buffer ptrs 
ONXTI,U | 


V.PORT,U 

Y.TYPE,U. E 

#589 Enable ACIA input interrupts 

Z,X 8 initialize ACIA for input inte ` 


return (carry clear) 


aleje lead alle a a a Be ai ae ae ie ak ae a ke oak dee ae ac ea aa ae kt ake de a ak ae ak geg 
return ONE BYTE cf input from the ACIA + 


* READ: 

x 

* PASSED: 
* 


READOO 


READ 


* 
(Y)=PATH DESCRIPTOR a 
(U)=STATIC STORAGE address Wé 
* RETURNS: (A)=input BYTE (carry clear) SE 
| CC=SET, B=ERROR code if error kd 
este te este fae al cal JES ae ae ea 2k SREB dte aH A teo OE He Sa A se ae 
BSR | ACSLEP wait for acia data l fn en 
LDB | INXTO,U (input buffer) NEXT-OUT ptr. 
LEAX INPBUF,U address of input buffer 
ORCC  #IROM. calm interrupts | 
CMP3 INXTI,U . any cata AVAILABLE? 
BEG READSO ` . No; wait, E retry 
ABX ` : 
IDA | 9,X the char 
INCB  . ADVANCE NEXT-OUT ELE: 
CMPB #INPSIZ-1 end of dcs LU SE 
BLS | READ19. ee NO 
CLRB |») reset ptr to. start of buffer. 
si | INXYTO,U save updated Buffer ptr 
LAB | | : | 


 READ19 


(C) 198g, 1981 Microware Systems corporation 


F-S 


DS —9 LEVEL ONE SYSTEM PRO GRAMER 'S MANUAL 
Avpe naix F: Semple bssemtliy dad rrograms -~ ACTA 


IDB > v.ERR U Transmission error? 


BEQ READO . ecko; return 
STE Ge? Y return errcr tits in PD 
CLR: V.ERR,U 
COMB return carry set 
LDB #ES$RD | Signal read error 
READSS SE ÉSFF-IRQM ^ erable IRQ requests 
. RTS | 


AE a CREA ACCC A AA 


ACSLEP - Sleep for I/0 activity 
This version HOGS CPU if signal pending 


(U)=Glotal Storage 
V.BUSY,U=current proc id 


DESTROYS: possibly PC 
ee 


TENTAR 


Sr 

Ss 

* 

* PASSED: (cc)=IRQ’s MUST be disabled. 
x 

x | 

Se 

sk 


ACSIEP  PSHS D,X | | 
LDA  V.BUSY,U get current process id 
STA V.WAKE,U arrange wake up signal 
ANDCC HS FF-IROM interrupts ck now 
 LDX HO | 
oss FSSLEP wait for input. data 
IDX  TD.PROC i 
LDB PSSIGN,X signal present? 


beg ACSLS£g =e NOS return 
cmpb #SSINTR |. Deadly signal? | 
B bls ACSLER ..Yes; return error 
ACSL9Y CLRB dk clear carry 
PULS D,X,PC return 
ACSLER LEAS 6,s Exit to caller” s caller 
eee e . Terura carry Set 
TS 


he ul d tfe ie a ae dee dee ee ak ak a ak BEE a de a de a ae a a ak ae ere ae ae akak ak ak Sake 


* WRITE char THROUGH ACIA * 
* - * 
* PASSED: (A)schar to write x 
T (Y)=PATH DESCRIPTOR 009 
* (U)=STATIC STORAGE address * 
* RETURNS: CC=SET IF BUSY (output buffer FULL) * 
EE 


WRIT700 BSR ACSLEP sleep a bit 
WRITE LEAX OUTBUF,U output buffer adcress 
| LDB  ONXTI,U (output) NEXT-OUT ptr 


ABX | 
STA g,X PUT char in buffer 
INCB | ADVANCE the pir 
CMPB  £O0UTSIZ-1 end of circular buffer? 
BLS WRIT19 DONO c 
| CLRB reset ptr to start of buffer. 
WRIT1@ ORCC #IRQM disable interrupts 


CMPB ONXTO,U buffer FULL? 


EE |» Microware Systems Open den 
"og Lid .F-19 


Q 


O 
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Sample EE Language Programs = ACTA 


Appendix F: 


GETSTA CMPA 
BNE 
LDA 
| SUBA 
ENE 
COMB 
LIB 
RTS 


GETS10  CMPA 


-PEQ 


| PUTSTA. COMB 


LDB 
RTS 


#55 .RDY 
GETS10 
INXTO,U 
INXTI,U 
WRITS 


HESNRDY 


4SS .EOF 
WRITOQ 


#ESUSVC 


BEC WRITES ..Yes; sleep and retry ` 
STR ONXTI,U save updated NEXT-IN ptr 
ANDCC #$FF-IROM enable IRQS | 9s, 
LIA CWITYPE,U ". PARITY CONTROL: E i 
ORA #SAD ENABLE input/output IRQS 
| STA [(V.PORT,U] ENABLE INTERRUPTS | 
WRIT99. CLRB (return carry clear) 
RTS | 
EE 
: GET/PUT ACIA STATUS S 
* PASSED: (A) =STATUS. CODE * 
* (Y)=PATH DESCRIPTOR: K 
* =- (U)=STATIC STORAGE address * 
* RETURNS: varies * 
EE RS a 


READY STATUS? 


es NO i 


any data AVAILABLE? 


-efES; retura carry clear 


End of file? 


.,.Yes; Return carry clear . 


return carry set 


UNKNOWN SERVICE CODE 


—— ae ae ae ae acaba be ae ae ae ae oe aka ae tee ae k 
* TERMINATE ACIA processing SE 
* a 


* PASSED: (U)=STATIC STORAGE : 
* RETURNS: NOTHING — 
EE ee ae a a a ee 


TRMNOO BSR 
TRMNAT LDX 
LDA 
STA 
STA 


(0) 1988, 1981 


ACSLEP 
D.PROC 
P$ID,X 
V.BUSY,U 
V.LPRC,U 
ONXTI,U 
#IRQM 
ONXTO,U 
TRMN20 
4503 


#$PF-IRQM 
#0 


EI? 


wait for I/0 activity 


disable interrurts 
output done? 
No; sleep a bit 


(VY. PORT ,U] disable ACIA interrupts 


enable interrupts 


remove acia from polling tbl 


. Microware Systems Corporation| 


Reli 


STEM PROGRAMER'S MANUAL 
embly Language Programs - ACIA 


T 


| 17 0$-9.LETEL ONE SY 
Appendix F: Sample Ass 


iSt d ac Be a ae ae ak a ae a K E ee ste We ak sie aie oe ote sie ele 
ACIRQ: Process INTERRUPT Sarat or pp) from ACIA x 


* 

>» ; 

* PASSED: (Uie STATIC STORAGE addr 
% | E Port address 

* (A)=polled status 

* 
3x 


soos gen 


-= Returns: NOTHING 
MR e RE t t ee d de t te fe a a ae a let fe a aK aKa defe je date tete ale a a lez eat ak aK ai ak a a ak a 


ACIRQ. — LX V.PORT,U get. EE address 
| ANDA #INPERR mask status error bits 
ORA | V.ERR,U. 


STA . V.ERR,U update cumulative errors 
LDA g,X . restore acia status 

BITA #1 - input ready? 

BNE INACIA ..yes; go get it 


aaa ae aaa ae steak akak me ot ae a aa dat ake a ak Sa a a de set ole e a eae a ea aa a 
__™ FALL THROUGH to DO output. 
TuS 


OACIA: Output to ACIA INTERRUPT ROUTINE 


Se 
*k 

. PASSED: (A)=ACIA STATUS REGISTER CONTENTS 
* (X)=ACIA port address. 
* 
Sr 


CR EN 


. (U)=STATIC STORAGE address | 
oe 


OACIA  LEAY OUTBUF,U output buffer ptr 


LDB ONXTO,U (output) NEXT-OUT ptr | 
cmrpb ONXTI, U output buffer already empty? 
beg .OACIA2 ` ..Yes; disable. outrut IRQ, ret 
CLRA | b y | | 
LDA D,Y nert output char 
INCE | ADVANCE NEXT-OUT ptr 
CMPB #OUTSIZ-1 end of circular bufíer? 
BLS OACIA1 +» «NO ! 
| CLRB ` ` | | 

OACIA1 STB ONXTO,U Save updated NEXT-OUT ptr 

STA 1,1: WRITE tne char 
CMPB ONXTI,U last char in output bef Ere 
ENE WAKEUP , «No 

OACIA2 LBSR INITSE disable output. Tdy IRQ 


WAKEUP LDB HS SWAKE WAKE UP SIGNAL 
LDA Y.WAKE,U OWNER WAITING? 
| WAKE1£ PEO WAK EOL e NO? return 
OS9 FSSEND 
WAKES® clr V.WAKE,U 
: RTS . 


(C) 1988, 1981. Microware Systems Corporation 
s O S 


08-9 LEVEL ONE SYS 


TEM PROGRAMER/S MANUAL 
Appendix PF: e Assembly Language E - ARIA 

a Rene a ok dete mec Te reer rr rere 
C * INACIA: Process ACTA input INTERRUPT * 
"AT + En 

* PASSED: (A) HACIA STATUS REGISTER data + 

* (X)=ACIA port address * 

*  (U)sSTATIC STORAGE address * 

x% * 


* NOTICE the ABSENCE of ERROR CEECKING HERE = 
ANE AE AE E 


 INACIA . LDA 1,X READ input char 
LEAX INPBUF, U input buffer 
-LDB INXTIT (input) NEXT-IN ptr 
ABX | 
STA g,X save char in buffer 
INCB update NEXT-IN ptr 
CMPB #INPSIZ-1 end of reeset buffer? 
BLS ACIA2 ..No | 
P CLRB | 
ACIA2 CMP8 INXTO,U input OVERRUN? 
| BNE ACIA25 ..No; good 


LDB #OVERUN mark overrun error 
ORB V.ERR,U i 
STB Y.ERR,U | 
e BRA ACIA26 throw away character 
ACIA25 STB INXTI,U update NEXT-IN ptr 


© 


ACIA26 ANDA #$7F | | | | 
"e “PEQ WAKEUP ..pass nulls without ctl check = 
CMPA V.PCHR,U FAUSE char? 
BNE ACIAS ..No 
LDX V.DEV2,U PAUSE DEVICE STATIC 
EEQ WAKEUP . None 
STA V.PAUS,X REQUEST PAUSE 
BRA WAKEUP | 


-ACIAS  — LDB  #S$INTR INTERRUPT SIGNAL 
CMPA V.INTR,U keyboard INTERRUPT SIGNAL? 


PEQ ACI AA 
LDE a ¡ORT SIGNAL 
CMPA .QUIT,U keyboard ABORT SIGNAL? ` 
SE ENE WAR BUD ..No | 
ACTAS IDA V.LPRC,U last process ID 
| BRA WAKE16 SEND ERROR SIGNAL 


emod Module CRC 


ACIEND EQU a 


(C) 1988, 1981 c Systems Corporation 
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Appendix F: Sample Assembly Language Frograms -~ PRINTERR 


————————————————— ESR Ho of SS SED A A a A ee 


* | | | | ES 
* PRINTERR - English Error Printer Module ` » 
` (C) 1981 Microware Systems Corpcration 3 


E 
MEERDE IE de eaten XR e a ale de HSA A AS AEE EE te eie ise see ee 


nam Printerr 


use /a@/defs/osoaets 


ifpi 

end 
EER ae esa cate ak ae alte ote RR tote ll ck aR AI de Hesse Des e dr a ae dese cte 
Printerr | | 00 X 
Translate OS-9 error numbers to English messages ` A 


Author: Bob Doggett 


Replaces OS-9 PRTERR service routine. . 
Note: once this is done, there is provision 
for returning to OS-°s original error routine. 


Speed could be improved, using fixed-length 
random file. The text file format used by this 
version may be edited, and is shorter then 

a random file would be. 


CAUTION: this version uses quite e chunk of 
User’s stack, and may be unsuitable for some 
processes. | | s 

ako ake zx at si a ak og ak ee a a ate zog aK ae ze He e oe se ae abe de ak ae oe ze xj fl e jeje te ae ope tesi ae ak ace o Ne ok aeo ie nie oe sete 


3t SS 3t 430 db d£ 3t G6 3b Gt d£ HEH HH 


Soo Gode MGR ER GRE RE 


| mod PEREND, FERNAM,PRGRM+CBJCT,REENI+1,PRIERR, 
PERNAN fcs  Printerr s s 


| fob 3 ` edition number mE 
BUFSIZ SET 80 ERRMSG FILE MAX RCD LENGTE 
C$CR SET — Aen | 


l "m————————À— 


* Frecution-Time Stack temporary storage * 
“aR ae ak a aK a de toe ete te ce cade ote a t EE sete de a e te eae ae je a t total 


ORG @. | | | 
PRTPTH RMB 1 User’s Std Error path 
ERRPTH RMB 1 ERRMSG path number | 
ERRNUM RMB 1 Error number 
|. BUFPTR RMB 2 Line buffer ptr. 
JOBUFF  RMB | BUFSIZ: Line buffer 
- PERMEM EQU Žž 


ERRFIL FCC "mei, 
ud FCC “ERRMSG 
FCB C$CR 


ERRMSG FCC “Error # 


b-14 
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Appendix F: Sample Assembly Language Programs - dq AR 


um | L^ 
Nur SVCT2L equ. * | .. Replacement for Iss cail vecto 
| fcd FSPERR 
.fáb PERROR-*-2 | Di 
fct $89 end of table EE 
BEAR E EEEE E EEE EE e E 
* Printerr: w 
oX | Translate 05-9 errors to English messages Kë 
A Kee message strings in EERMSG file is 
* Format of ERRMSG file: | * 
* Number (8-3) Ascii error number (8-255) * 
* Delim 1 Any byte <= $21 > 
* Message (£-n) Variable length message string * 
xj ic soie he ae ake ak af e ak ak ak RM EE RE Rede xc HE AD a ARE Ee AE tte 
-PRIERR CLRA 
LEAX <PERNAM,PCR 
0S9 FSLINK Link to self 
BCS EXIT "` «Error; Fail 
LEAY <SVCTBL,PCR | 
0S9 . F$SSVC redirect system prterr routine 
CLRB. e | 
is EXIT GER FSEXIT 
e FERROR LDX D.PROC | 
e 2 — LDA PSPATH+2,X Get user’s std error path 
BEQ PERROO ..None; exit 
LEAS -PERMEM,S chop out temp storage 
LDB RSB,U ; 
LEAU 9,5 
STA PRIPTH, U 
STE ERRNUM,U Save error number - 
BSR PRTNUM print “Error ën 
LDA BREAD. 
LEAX  ERRFIL,PCR ERRMSG file name 
0S9 ISOPEN ^. | 
STA ERRPTE,U save path number 
ECS PERR99 + «ERROR; exit 
BSR SEARCH find error in ERRMSG file. 
ENE PERRSU Not found; exit 
BSR . PRTLIN print Error Message 
PERR89 LDA ERRPTE,U 
059 I$CLOS ^ close ERRMSG file 
PERRS2 LEAS PERMEM,S l 
RTS 
SEARCH LDA  ERRPTH,U 
| LEAX IOBUFF,U. 
ES | LDY #BUFSIZ mo 
mom x 0S9 ISRDLN - read one ERRMSG RCD 
Nu BCS SEAR9Q «ERROR EXIT 
BSR GETNUM get number in I/O bufter 
COMPA eu: Followed by separator? 


(C) 1989, 1981 .  Microware Systems Corperation 
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Appendix F: Semple Assembly Language Progrems - PRINTERR 


SEARSO 


BES 


CMPB 
ENE 
RTS 


SEARCH 
ERRNUM,U 


 SEARCE 


..n0; Skip this record 

IS this the Error nunterí 
..No; REPEAT 

RETURN 


(aote ae aca ak ae ak ak Wee ie ak ae ak ak aa a BEDE x a ica aK aK ale ak ak a de ak ak ak HE a 


SS PRTNUM: 


PRINT 8-BIT ASCII NUMBER IN (,X+) * 


BE oh zh ahs SE de de ahs ak ae aie atc ee i de ae aie Bic aK as AAR e BE Se aK A OK IKE SA OK NE ANCHE e IR ANE ORIS Bs AE 


PRE NUM 


 PRTNO5 


PRTN12 


PRTN20 


PRTLIN 
PRINT 


GETNUM 
GETN192 


GETNSÜ 


PER END 


LEAX 
LEAY 
LDA 


STA. 


LDA 
BPL 
LDB 
LDA 


INCA 
SUBB 4 


ECC 
STA 
LDA 
DECA 
ADDB 
-BCC 
STA 
TFR 
ADDA 


-LDB 


STD 
LEAX 
LDY 
LDA 


. 0S9 
RTS 


CLRB. 


LDA 
SUBA 
CMPA 
BHI 
PSES 
LDA 
MUL 
ADDS 
BCC 


LIA 


RTS 
emod 


EQU 


ERRMSG,PCR ptr to “Error 8^. 


IOBUFF,U 
+ 


MEN 


#10 


IOBUFF,U 
#80 
PRTPTE,U 
ISVRLN 


Xt 
#°2 

#9 

GET NS@ 
A 

810 


T 
GETN10 ` 
-1,X 


E 


(C) 1982, 1981 


form hundreds digit 


Put hundreds digit in buffer 


form tens digit 


Put tens digit in buffer 
form units digit 


Put units digit in buffer 


Print to STD Error path 


J Numeric character? 
..No5; done 
save digit 


multiply partial result by 1@ 
add in next digit 

..Continue until overflow 
retreive separator character 


: Module CRC 


|» .Microware Systems Corporation. 
EP Lum d SC? 


C) 


OS-G LEVEL ONE SYSTEM PROGRAMMERS MANUAL - 
SE G: Service request maty 
SERVICE REQUEST SUMMART 

USER MODE FUNCTION REQUESTS 
CODE MNEMO NIC FUN NCTION PAGE 
183F 9a FSLINK. Link to memory module. - - mmm ve D 
1e3* 01 FSLOAD Load module from mass-storage ~ - 7 € 
123F 22 XeUNIK ^.  Unlink module. e: =-=- TJ" 
195r 03 FOFORK Start now process. AE RA € = 59 
103F 94 F$WAIT wait for signal em mms. 78 
103F 95 F$ CHAN Chain process to new ‘module - = = Sc 
103F 0€ FSEXIT Terminate Process - “ms me mmm. SE 
1803F @7 |» F$MEM Set memory size ~~~ ~ ~- ms ss C5. 
193F 08 FSSEND Send signal to process -= == 7 = =- +65 
103F 09 |. FSICPT Set signal intercept trap = “o “.-:. DÄ. 
1233 ØA FSSLEP Suspend process" € RR HE RR AO 
103F OB | |. Kot implemented | | 
1g3F 2C FSID Return process dpm = =s = m e 62 
103F ØD FSSPRI Set process priority = ss e 94 71 
103F OF FSSSWI Set software interrupt vector ~- -- Té 
103F OF ` FSPERR Print error message oo o 667 
1931 19 FSPNAM Parse pathlist name -77 =] = “OY 
103F 11 FSCNAM . Compare two names ee ' 68 
1@3F 12 F$SaIT. Search a fit Map == Me. 9 65 
103F 13 FSABIT Allocate in a bit map ~= ~m = = = 52: 
193F 14 FSDEIT Deallocste in a tit map, sea E Se 
195* 15 FSTIME Beturm current time sm er 9027 = TO een 
1931.16 c F$STIM Set current tipe ==“ ere E TEE 0S. 
1803F 17 FSCRC Generate CRC oss - sesse 56 
SYSTEM MODE FRIVILEGED FUNCTION REQUESTS 
GODE MNEMONIC FUNCTION PAGE 
103 28 FSSRGM ¿System memory request == =- = -= =. 87 
103F 29 F$SRTM System memory return 7 = = = === ~ 68 
1@3F 24 ESIRQ ` Enter IRQ polling table eme EE 
123F 28B F$IOQU Enter 1/0 queue --7 =- = = = err 33 
103F 20 FSAPRC Enter active process queue. e e e Be 
ig3F 2D — FSNPRC - Start next process mmm mis RR E 
103F 2E FSVMOD «Validate module === - === 8898 
103F 2F FSFE4 Fina 64 byte memory block ----- ai 
Loi 32 F$A64 Allocate a 64 tyte memory block - = 79 
183 31 FSR64 Return a 64 byte memory block = - ~ c6 
193* 32 - FSSSVC* Install a function request e | 2 
1893F 33 FSIODL Delete 1/2 module ee = oT Dm 82 


*NOTE: FSSSVC is a user mode function, although its code > $27 


(C) 1980, 1981 Microware Systens Corporation 
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. Appendix 6: 


OG RAMMERS MANUAL. 
Le Quest Summary 


-— 
vé 
de 
m 
E 


Service 


INPUT/OUTPUT SERVICE RzQUESTS. 


CODE MNEMONIC ^ FUNCTION | d PAGE 
123% 80 ISATCH “Attach 1/0 device op + =o |o mim = e0 BE. 
KEN ISDTCE Detach 1/0 device -—-------- SC 
193* 82 ISTUP Duplicate: peti e EE Me ee HY 
103F 83 Se | Create a new file ere AE = wom : 395 
123F 84 OPEN Open a path to an existing file - = 105 
103F 85 ISMDIR Make a directory file ------+>- 182 
193* 86 de Change working EE Pues eh oe eee S1. 
123F 87 ISDLzT Delete. @ file (See So ES EL ~ E 
123F 88 ISSEEK Rerosition file pointer ————-—- 198 
125r: 89 ISREAD ^ - Read date —-—-—--—----—------ l5 
103F 8A |J I$WRIT Write data = == = == -= === - = 110 
103F 83 ISRDLN Read line == == ===“ 105 
1£83F 8C SEN Write line = == === ==“ = == iii 
123F 8D ISGSTT Get device status =~- mms + = = = = 98 ` 
103F BE I$SSTT Set device status mr RE m mem 127 | 
193* 8F . I$CLOS Dlosc.e path. — — RE eae <= 92 


A e e O A a E e ea 


D = Standard 
1 = Standard 
2 = Standard 


MODUIE TYPES 


ge GEM MU (UE VINE (URP gë vm UU RD MD e 


- oma up gem, QUUD géie ADU QUU QUE AMOR QUE VE GUED NUM em QUEM. OS OF. QUID. GUI. DEP due GU. fe a an Eg EE te ee ce ——MÀ—— À—————Ó——— me 


PATHS . FILE ACCESS CODES 
Input READ = $21 
Output WRITE = $22 
Error Output UPDATE. = READ + WRITE 
EXEC = $94 
PREAD = 508 
PWRIT = $12 
PEXEC = $20 
SHARE = $42 
DIR = $82 


$1 = Program 

$2 = Subroutine Module 
.$8 = Multi-Module 

$4 - Data 

$C = System Module 
.$D = File Manager 

$E = Device Driver 

$F = Device Descriptor 


Ee 


MODULE LANGUAGES 


Data 

6509 Object. code 
BASIC2O I-Code 
Pascal P-Code 


Af 
GN 
-— "og od 


MODULE ATTRIBUTES 


em AD aen, EL Au qvo GR AUI. AUD ee UD. M MD m 


-$8 = Reentrant. 


1681 ae systems Corporation. 
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EM PROGRAMMERS MANUAL 
Appendix B: 05-9 Error Codes 


0S-3 ERROR CODES 


The error codes are shown in toth nexadecimal (first EYE and 
decimal (second column). Error codes otner tnan those listed 
are generated by programming SR or user programs. 


HEX DEC 


em euer eae -— w— aoe 


¿083 200 PATH TABLE FUIL - The file cannot be opened tecause. 
^ the system path tatle is curreatly full. 


$C9 201 ILLEGAL PATH NUMBER — Number too Kc or for 
non-existant path. | 


CA 202 INTERRUPT POLLING TABLE FULL 


¿CB 203 ILLEGAL DEVICE - Can't find device descriptor, 
. file manager or device driver. 


&$CC 204 DEVICE TABLE FULL - Can't add anotner device. 


$CD 225 ILLEGAL MCDULE. HEADER - Modules. sync code, check 
character. or CRC is incorrect. 


$CE 206 MODULE DIRECTORY FULL ~ Can't add another module 


SCF 287 MEMORY FULL - Not enough contiguous RAM 
avallable to process request. 


rg 208 ILLEGAL SERVICE REQUEST - System call had an 
illegal code number. 


$D1 209 MODULE BUSY - non-sharatle EE is in use by 
another process.. | 


$p2 21 BOUNDARY ERROR - Memory allocation or SE 
request not on page boundary. 


$D3 211 END OF FILE - End of file encountered on read. 


 $D4 212 NOT YOUR MEMORY - attempted to deallocate memory 


not previously assigned. 


$D5 2138 NON- EXISTING SEGMENT - device has damaged file 
structure. 


$p6 214 NO PERMISSION - you don’t have owner's nermission 
to access the file as requested. ` | 


4D? 215 BAD PATH NAME - syntax error in pathlist. 


(6) 1582, 1981 Microware ysters. Corporation. 
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Appendix E: -05-9 Error Codes ^ 


ERROR CODES (continued) 


DEC 


216 MISSING PATELIST - expected pathlist missing or 


in error. 


217 SEGMENT LIST FULL - file is too fregmented to 


be E further. 


. 218 FILE ALREADY EXISTS - file name already appears 


in current Girectory. 


219 ILLEGAL BLOCK ADDRESS - device ^s file Se 


has beer dameged. 


220 ILLEGAL BIOCK SIZE - device’s file struct ed 


has been damaged. 


221 MOTULE NOT FOUND - request for link to module 


not found in directory. ` 


222 SECTOR OUT OF RANGE - device file structure 


damaged or incorrectly formatted. 


223 SUICIDE ATTEMPT = request to return memory ` 


where your stacx is located. 


224 ILLEGAL PROCESS NUMBER — no such process 
exists. l 


225 ILLEGAL SIGNAL CODE. 


226 NO CHILDREN - can't wait because process 
has no children. i 


227 ILLEGAL SWI CODE ~ must be 1 to 3. 


228 KEYBOARD ABORT - process aborted by 
signal code 2. 


229 EE TABLE FUIL - can’t ii now. 


269 LLEGAL PARAMETER AREA - high and low bcunds. 


passed in fork call are incorrect. 


221  BACKTRACK ERROR - you “11 never see EIE 


(C) 1982, 
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‘Appendix Hr 05-9 Error Codes 


OS-9 ERROR CODES (continued) 


HEX DEC 


emm emm, ëm em eme ip 


$EB 234 SIGNAL ERROR - receiving process has previous 
| unprocessed signal pending. 


-— DEVICE DRIVER/HARDWARE ERRORS -- 


$50 240 UNIT ERROR - device unit does not exist. 

$71 241 SECTOR ERROR “Sector samber i$ out of e 
5F2 242 WRITE PROTECT - device is write protected. 

$F3 243 CRC ERROR - CRC error on read or write verify. 


$F4 244 READ ERROR - Data transfer error during dis read 
operations 


GK 245 WRITE ERROR - hardware error ie disk: aar E E 
write operation. | 


are 246 NOT READY - device has "not ready status. 
po 247 SEIK ERROR - physical seek to non-existant sector. 
¿Pg 248 MEDIA FULL - | insufficient free space on media. 


Are 249 WRONG TYPE - attempt to reed incompatible media (i T 
SES to read double-side disx on sirgle-side drive) 


(C) 1980, 1981 Microware Systems Corporation ` 


